explain-dependencies 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2aa688fbd10f5081f121eb0ba23ab37a27db9298
+  data.tar.gz: 89f5fb3afffb575a54a04f1102dcaeee14202a8d
+SHA512:
+  metadata.gz: a78e7c7bbd2ab7d2a16190c4f558c7fe4a908125cc3dda44c0a05b9f555118b3665e7039c218c48561dbab8d7d3f7605f05c46f49340698a855445eb9b48cdd7
+  data.tar.gz: 8b4b694b06f0816f11931d4b2df8e3f7c33923dbdb49fce7772ce5c9fe2495cf064f6aeeaeeaeb2f7f19d3889817ff496afa9f239a0e589f3b14bd1c5dc3b61c

data/README.md

@@ -0,0 +1,65 @@
+# Explain Dependencies
+
+Explains what your project's dependencies are.
+
+
+## Installation
+
+[Ruby](https://www.ruby-lang.org/en/downloads/) is required. Once it's installed run:
+
+    gem install explain-dependencies
+
+If you're using [Bundler](http://bundler.io/):
+
+    gem "explain-dependencies", :group => :development
+
+## Usage
+
+    xdep [-ai] [-f format] [file or directory...]
+      -a, --add                        Add explanations to the dependency file, if possible
+      -i, --ignore-popular             Ignore popular dependencies
+      -f, --format=NAME                Output format for explanations (csv or source), defaults to csv
+
+Your dependencies must be installed in order to describe them.
+
+### Output Formats
+
+Explain Dependencies can output to CSV or add descriptions to the
+dependency file.
+
+CSV output will contain the following columns: Language, Name,
+Version, Description, Homepage, License
+
+Source output adds the dependency's description as a comment
+directly above the line that's including it. This is not supported for
+all output formats.
+
+### Examples
+
+Output a CSV file describing all of your project's dependencies:
+
+    xdep
+
+Output a CSV file describing dependencies in `package.json`:
+
+    xdep package.json
+
+Output a `Gemfile` with comments describing dependencies in `Gemfile`:
+
+    bundle exec xdep -f source Gemfile
+
+Update your project's `Gemfile` with comments describing each
+dependency, ignoring well-known dependencies:
+
+    bundle exec xdep -aif source Gemfile
+
+## Supported Projects
+
+* Ruby: [Bundler](http://bundler.io/v1.15/man/gemfile.5.html), [RubyGems](http://guides.rubygems.org/specification-reference/)
+* Node: [npm](https://docs.npmjs.com/getting-started/using-a-package.json)
+
+## TODO
+
+* More dependency files
+* Specify CSV columns
+* Speedup describing package.json

data/bin/xdep

@@ -0,0 +1,41 @@
+#!/usr/bin/env ruby
+
+require "optparse"
+require "xdep"
+
+options = {
+  :add    => false,
+  :format => :csv,
+  :ignore => false
+}
+
+parser = OptionParser.new do |opts|
+  opts.banner = "usage: #{File.basename($0)} [-ai] [-f format] [file or directory...]"
+
+  opts.on "-a", "--add", "Add explanations to the dependency file, if possible" do
+    options[:add] = true
+    options[:format] = :source
+  end
+
+  opts.on "-f", "--format=NAME", %w[csv source], "Output format for explanations (csv or source), defaults to csv" do |f|
+    options[:format] = f.to_sym
+  end
+
+  opts.on "-i", "--ignore-popular", "Ignore popular dependencies" do |n|
+    options[:ignore] = true
+  end
+
+  opts.on "-v", "--version", "Display version number" do
+    puts "v#{XDep::VERSION}"
+    exit
+  end
+end
+
+parser.parse!
+
+sources = ARGV
+sources = [Dir.pwd] unless sources.any?
+
+puts "Checking dependencies..."
+XDep.new(options).process(sources)
+puts "Done"

data/lib/xdep.rb

@@ -0,0 +1,108 @@
+require "fileutils"
+require "tempfile"
+
+require "xdep/npm"
+require "xdep/ruby"
+require "xdep/version"
+
+class XDep
+  Error = Class.new(StandardError)
+
+  REPORT_BASENAME = "dependencies".freeze
+  REPORT_EXTENSION = ".explained".freeze
+
+  FORMAT_HANDLERS = {
+    :csv    => [ Bundler::CSVOutput, RubyGems::CSVOutput, Npm::CSVOutput ],
+    :source => [ Bundler::GemfileOutput, RubyGems::GemspecOutput ]
+  }
+
+  def initialize(options = nil)
+    @options = options || {}
+    @format = @options[:format] || :csv
+    raise ArgumentError, "Unknown output format: #{@format}" unless FORMAT_HANDLERS.include?(@format)
+  end
+
+  def process(sources)
+    sources = normalize_sources(sources)
+    raise ArgumentError, "No dependency files found" if sources.empty?
+
+    if @format == :csv
+      output_as_csv(sources)
+    else
+      output_as_original(sources)
+    end
+  end
+
+  private
+
+  def output_as_original(sources)
+    handlers = create_handlers(sources)
+
+    sources.each do |source|
+      File.open(source) do |input|
+        output = Tempfile.new(REPORT_BASENAME)
+        begin
+          # TODO: Not sure this is the right interface
+          handlers[File.basename(source)].process(input, output)
+          output.close # On Win files must be closed before moving.
+          dest = source
+          dest += REPORT_EXTENSION unless @options[:add]
+          FileUtils.mv(output.path, dest)
+        ensure
+          output.close unless output.closed?
+        end
+      end
+    end
+  end
+
+  def output_as_csv(sources)
+    handlers = create_handlers(sources)
+    report = File.open("#{REPORT_BASENAME}.csv", "w")
+
+    begin
+      sources.each do |source|
+        # Each handler must append
+        report.seek(0, :END)
+        File.open(source) do |input|
+          handlers[File.basename(source)].process(input, report)
+        end
+      end
+    ensure
+      report.close
+    end
+  end
+
+  def normalize_sources(sources)
+     sources.flat_map do |source|
+      if File.directory?(source)
+        find_sources(source)
+      elsif !File.file?(source)
+        raise ArgumentError, "No such file: #{source}"
+      elsif find_handler(File.basename(source)).nil?
+        raise ArgumentError, "Don't know how to output #{source} in #@format format"
+      else
+        source
+      end
+    end
+  end
+
+  def create_handlers(sources)
+    sources.each_with_object({}) do |source, h|
+      basename = File.basename(source)
+      unless h.include?(basename)
+        klass = find_handler(basename)
+        raise Error, "#{basename} does not support format #@format" unless klass
+
+        h[basename] = klass.new(@options)
+      end
+    end
+  end
+
+  def find_handler(filename)
+    FORMAT_HANDLERS[@format].find { |handler| handler.accepts?(filename) }
+  end
+
+  def find_sources(root)
+    Dir[ File.join(root, "*") ].reject { |path| find_handler(File.basename(path)).nil? }
+  end
+end

data/lib/xdep/composer.rb

@@ -0,0 +1,5 @@
+module XDep
+  module Composer
+
+  end
+end

data/lib/xdep/npm.rb

@@ -0,0 +1,64 @@
+require "json"
+require "xdep/output"
+
+class XDep
+  module Npm
+    class CSVOutput < XDep::CSVOutput
+      KNOWN_DEPENDENCIES = []
+
+      def self.accepts?(filename)
+        filename == "package.json"
+      end
+
+      protected
+
+      def known_dependencies
+        KNOWN_DEPENDENCIES
+      end
+
+      def get_rows(input)
+        rows = []
+
+        Dir.chdir(File.dirname(input.path)) do
+          # This is very slow...
+          ls.each do |name, version|
+            info = describe("#{name}@#{version["version"]}")
+            license = info["licenses"] ? format_licenses(info["licenses"]) : info["license"]
+            rows << [ "JavaScript", name, version["version"], info["description"], info["homepage"], license ]
+          end
+        end
+
+        rows
+      end
+
+      private
+
+      def ls
+        out = `npm ls --depth=0 --json 2>&1`
+        raise Error, "Failed to execute npm: #{out}" unless $?.exitstatus.zero?
+        parse_json(out)["dependencies"]
+      end
+
+      def describe(pkg)
+        # Include license and licenses else we won't get JSON output if one doesn't exist
+        out = `npm view #{pkg} description homepage license licenses --json 2>&1`
+        raise Error, "Failed to execute npm: #{out}" unless $?.exitstatus.zero?
+        parse_json(out)
+      end
+
+      def parse_json(out)
+        JSON.parse(out)
+      rescue JSON::ParserError => e
+        raise Error, "Failed to parse npm output: #{e}"
+      end
+
+      def format_licenses(licenses)
+        licenses.map do |data|
+          s = data["type"]
+          s << " (#{data["url"]})" if data["url"]
+          s
+        end.join(", ")
+      end
+    end
+  end
+end

data/lib/xdep/output.rb

@@ -0,0 +1,44 @@
+require "csv"
+
+class XDep
+  class Output
+    def initialize(options = nil)
+      @options = options || {}
+    end
+
+    def self.accepts?(filename)
+      raise NotImplementedError
+    end
+
+    protected
+
+    def known_dependencies(name)
+      [].freeze
+    end
+
+    def ignore?(name)
+      @options[:ignore] == true && known_dependencies.include?(name)
+    end
+  end
+
+  class CSVOutput < Output
+    HEADER = %w[Language Name Version Description Homepage License].freeze
+
+    def process(input, output)
+      rows = get_rows(input)
+      rows.sort_by! { |r| r[1] }
+
+      mode = output.pos.zero? ? "w" : "a"
+      CSV.open(output, mode) do |csv|
+        csv << HEADER if output.pos.zero?
+        rows.each { |r| csv << r }
+      end
+    end
+
+    protected
+
+    def get_rows(input)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/xdep/ruby.rb

@@ -0,0 +1,129 @@
+require "xdep/output"
+
+class XDep
+  module Ruby
+    module Helper
+      COMMENT = /\A\s*#/
+      GEMFILE = /\A(\s*)gem\s+(["'])(\S+)\2/
+      GEMSPEC = %r|\A(\s*)\w+\.add(?:_development)?_dependency[(\s+]?(["'])(\S+)\2|
+
+      # I think 2.4.0 added MissingSpecError
+      SPEC_MISSING = defined?(Gem::MissingSpecError) ? Gem::MissingSpecError : Gem::LoadError
+
+      # > 50 million downloads according to rubygems.com, with a few exceptions
+      KNOWN_DEPENDENCIES = %w[
+        actionmailer actionpack actionview activemodel activerecord
+        activesupport addressable arel aws-sdk builder
+        bundler coderay coffee-rails coffee-script coffee-script-source
+        daemons diff-lcs erubis eventmachine execjs
+        faraday ffi hike i18n jquery-rails
+        json mail method_source mime-types mini_portile
+        minitest multi_json multipart-post mysql2 net-ssh nokogiri
+        polyglot pry rack rack-test rails
+        railties rake rest-client rspec rspec-core
+        rspec-expectations rspec-mocks rspec-support rubygems-bundler sass
+        sass-rails sinatra slop sprockets sprockets-rails sqlite3
+        thor thread_safe tilt tzinfo
+        uglifier
+      ].freeze
+
+      private
+
+      def known_dependencies
+        KNOWN_DEPENDENCIES
+      end
+
+      def output_ruby(input, output, match)
+        last_line = nil
+        input.each_line do |line|
+          if line =~ match
+            lead = $1
+            name = $3
+
+            if !ignore?(name)
+              spec = find_spec(name)
+              next unless spec
+
+              comment = "#{lead}# #{spec.summary}"
+              # Allow for multiple runs without adding the comment over and over
+              # strip to account for changes in indentation
+              output.puts(comment) unless last_line.strip == comment.strip
+            end
+          end
+
+          last_line = line
+          output.puts(line)
+        end
+      end
+
+      def find_spec(name)
+        Gem::Specification.find_by_name(name)
+      rescue SPEC_MISSING
+        raise Error, "Cannot find dependency #{name}; is it installed locally?"
+      end
+    end
+
+    class CSV < XDep::CSVOutput
+      include Helper
+
+      def self.accepts?(filename)
+        Bundler::GemfileOutput.accepts?(filename) || RubyGems::GemspecOutput.accepts?(filename)
+      end
+
+      protected
+
+      def get_rows(input)
+        rows = []
+
+        input.each_line do |line|
+          next if line =~ COMMENT || line !~ GEMFILE && line !~ GEMSPEC
+          next if ignore?($3)
+
+          spec = find_spec($3)
+          if spec.nil?
+            row = [$3, nil, "Gem not found"]
+          else
+            row = [spec.name, spec.version.to_s, spec.summary, spec.homepage, spec.licenses.join(", ")]
+          end
+
+          row.unshift "Ruby"
+          rows << row
+        end
+
+        rows
+      end
+    end
+  end
+
+  module RubyGems
+    CSVOutput = Ruby::CSV
+
+    class GemspecOutput < Output
+      include Ruby::Helper
+
+      def self.accepts?(filename)
+        (filename =~ /\w\.gemspec\z/) != nil
+      end
+
+      def process(input, output)
+        output_ruby(input, output, GEMSPEC)
+      end
+    end
+  end
+
+  module Bundler
+    CSVOutput = Ruby::CSV
+
+    class GemfileOutput < Output
+      include Ruby::Helper
+
+      def self.accepts?(filename)
+        filename == "Gemfile"
+      end
+
+      def process(input, output)
+        output_ruby(input, output, GEMFILE)
+      end
+    end
+  end
+end

data/lib/xdep/version.rb

@@ -0,0 +1,3 @@
+class XDep
+  VERSION = "0.0.1"
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: explain-dependencies
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Skye Shaw
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-09-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: Explains what your project's dependencies are. Export to CSV or add descriptions
+  as code comments.
+email: skye.shaw@gmail.com
+executables:
+- xdep
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- bin/xdep
+- lib/xdep.rb
+- lib/xdep/composer.rb
+- lib/xdep/npm.rb
+- lib/xdep/output.rb
+- lib/xdep/ruby.rb
+- lib/xdep/version.rb
+homepage: http://github.com/sshaw/explain-dependencies
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.12
+signing_key: 
+specification_version: 4
+summary: Explains what your project's dependencies are.
+test_files: []