cocoapods-why 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cf607f5706da9f9cffa9cdac50e702f3c9e2fbf305f2674121102dfda5b80a01
+  data.tar.gz: 07625dc6f38f2728f818bc4890d4809d19d51e9899ca9065d320c7ae0d461407
+SHA512:
+  metadata.gz: 43a3893be1ee319fdced20be09c9ad7e751e5c0b4d2d76ce0704878c69fcb0b9be34956ac3326611ff156cf5dc9bfb36af2edfc405ab22af274b8e7e7befc7fe
+  data.tar.gz: 5ba60b6bc840b2c23edea06b345cab24d8c03bd9db0dc11e1344da578cedd361deb311e7b84fbb74bc782cefca4bc465739f7e50c89c482db8282ed659225145

data/CONTRIBUTING.md

@@ -0,0 +1,16 @@
+Contributing
+============
+
+If you would like to contribute code to cocoapods-why you can do so through GitHub by
+forking the repository and sending a pull request.
+
+When submitting code, please make every effort to follow existing conventions
+and style in order to keep the code as readable as possible. Please also make
+sure your code has tests.
+
+Before your code can be accepted into the project you must also sign the
+[Individual Contributor License Agreement (CLA)][1].
+
+
+ [1]: https://spreadsheets.google.com/spreadsheet/viewform?formkey=dDViT2xzUHAwRkI3X3k5Z0lQM091OGc6MQ&ndplr=1
+ 

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2020 Square, Inc.
+ 
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+ 
+    http://www.apache.org/licenses/LICENSE-2.0
+ 
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -0,0 +1,77 @@
+# Introduction
+
+This plugin for CocoaPods helps understand the dependencies between two pods. It is intended for projects with a large number of dependencies.
+
+The plugin's output can be saved to YAML format for easy parsing by other tools (e.g. a CocoaPods GUI) or to GraphViz format for visualization.
+
+# Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'cocoapods-why'
+
+And then run:
+
+    $ bundle
+
+Or, install it system-wide with:
+
+    $ gem build cocoapods-why.gemspec
+	$ gem install cocoapods-why-1.0.0.gem
+
+Or, in a single command:
+
+    $ bundle exec rake install
+
+# Usage
+
+The plugin adds a `why` command to CocoaPods. You can get help on its parameters with:
+
+    $ pod why --help
+
+## All Paths Between Pods
+
+The most common usage of the `why` command is to show all paths between two pods Foo and Bar:
+
+    $ pod why Foo Bar
+
+This is helpful for understanding why a particular pod has a transitive dependency on some other pod (possibly one you do not want). By default, it simply lists the paths, but it can also produce a graph of them.
+
+## All Paths To A Pod
+
+The `why` command can also show all pods that depend on some other pod, either directly or transitively.
+
+    $ pod why Foo
+
+This is helpful for finding the set of pods that consume a particular pod and will have to be rebuilt (or could break) if it changes. By default, the command lists all of the pods, but it can also produce a graph of them.
+
+# Graphing
+
+The `why` command can produce a graph of its output with the `--to-dot` argument, which takes a file name as a parameter. The output file will be in [DOT format](https://en.wikipedia.org/wiki/DOT_\(graph_description_language\)), which can be visualized with a DOT processor. For example, you can generate a PDF from a DOT file with this GraphViz command:
+
+    $ dot -Tpdf dependencies.dot > dependencies.pdf
+
+# Caching
+
+Finding pods in the CocoaPods project can take a long time when there are many dependencies. To speed things up, the `why` command accepts a `--cache` parameter, which is used to specify a YAML file containing previous output from the [`query --to-yaml`](https://github.com/square/cocoapods-query) command (from the [query plugin](https://github.com/square/cocoapods-query)). When the plugin sees the `--cache` parameter, it will use the data in this file instead of rebuiding the data from the current CocoaPods instance.
+
+# Related Work
+
+This plugin was inspired by:
+
+* [yarn why](https://classic.yarnpkg.com/en/docs/cli/why/): It is similar to `pod why` but additionally provides information on the file sizes of the dependencies.
+* [bazel query](https://docs.bazel.build/versions/master/query-how-to.html): Bazel offers a query language that can find the paths between two dependencies with `bazel query "allpaths(...)" --graph`.
+* [dependencies](https://github.com/segiddins/cocoapods-dependencies): This CocoaPods plugin produces a graph of a single pod's dependencies.
+* [graph](https://github.com/erickjung/cocoapods-graph): This CocoaPods plugin produces a wheel graph of all dependencies in a project.
+
+# Development
+
+For local development of this plugin, the simplest approach is to install it into an existing app via absolute path. For example, if the code is in a directory called `projects/cocoapods-why` off the home directory, add the following line to the app's Gemfile:
+
+    gem 'cocoapods-why', path: "#{ENV['HOME']}/projects/cocoapods-why"
+
+You can then make changes to the code and they will be executed when using the `why` command from the app's directory.
+
+# Copyright
+
+Copyright 2020 Square, Inc.

data/lib/cocoapods_plugin.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'pod/command/why'

data/lib/cocoapods_why.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CocoaPodsWhy
+  VERSION = '1.0.0'
+end

data/lib/pod/command/why.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require 'cocoapods'
+require 'rgl/adjacency'
+require 'rgl/dot'
+require 'rgl/implicit'
+require 'rgl/traversal'
+require 'yaml'
+
+module Pod
+  class Command
+    class Why < Command
+      self.summary = 'Shows why one pod depends on another'
+      self.description = 'If both source and target are given, all paths between them are shown. If target is omitted, all pods that depend on the source (directly or transitively) are shown.'
+
+      self.arguments = [CLAide::Argument.new('source', true), CLAide::Argument.new('target', false)]
+
+      def self.options
+        [
+          ['--to-yaml=FILE', 'Output the results in YAML format to the given file'],
+          ['--to-dot=FILE', 'Output the results in DOT (GraphViz) format to the given file'],
+          ['--cache=FILE', 'Load the dependency data from the given YAML file (created previously with the "query" command) instead of from the current CocoaPods instance']
+        ].concat(super)
+      end
+
+      def initialize(argv)
+        super
+        @source = argv.shift_argument
+        @target = argv.shift_argument
+        @to_yaml = argv.option('to-yaml')
+        @to_dot = argv.option('to-dot')
+        @cache = argv.option('cache')
+      end
+
+      def validate!
+        super
+        help! if @source.nil?
+      end
+
+      def run
+        UI.puts 'Loading dependencies...'
+        all_dependencies = all_dependencies(targets)
+        [@source, @target].compact.each { |pod| help! "Cannot find pod named #{pod}" if all_dependencies[pod].nil? }
+        graph = make_graph(all_dependencies)
+        @target.nil? ? find_reverse_dependencies(@source, graph) : find_all_dependency_paths(@source, @target, graph)
+      end
+
+      private
+
+      # Returns an of array of all pods in the sandbox with their dependencies. Each element
+      # in the array is a hash of the pod's name and its dependencies.
+      #
+      # If a cache is present, the array is loaded from it instead of from the current instance.
+      #
+      # @note For projects with a large dependency graph, this function can take a long time to
+      #       run if a cache is not given.
+      #
+      # @return [Array<Hash>] an array of hashes containing pod names and dependencies
+      def targets
+        return YAML.safe_load(File.read(@cache), permitted_classes: [Symbol]) unless @cache.nil?
+
+        targets = Pod::Config.instance.with_changes(silent: true) do
+          Pod::Installer.targets_from_sandbox(
+            Pod::Config.instance.sandbox,
+            Pod::Config.instance.podfile,
+            Pod::Config.instance.lockfile
+          ).flat_map(&:pod_targets).uniq
+        end
+
+        targets.map { |target| { name: target.name, dependencies: target.root_spec.dependencies.map(&:name) } }
+      end
+
+      # Returns a hash of all dependencies found in the given target list. The keys of the hash are
+      # pod names and their values are the direct dependencies for that pod (represented as an array
+      # of pod names). Pods with no dependencies are mapped to an empty array.
+      #
+      # @param [Array<Hash>] targets
+      #        An array of hashes containing pod names and dependencies
+      #
+      # @return [Hash<String,Array<String>>] a mapping of pod names to their direct dependencies
+      def all_dependencies(targets)
+        targets.to_h do |target|
+          target_dependencies = target[:dependencies].delete_if { |dep| dep.include? '/' } # Remove subspecs
+          [target[:name], target_dependencies]
+        end
+      end
+
+      # Returns a directed dependency graph of all pods in the sandbox. The vertices are pod names, and
+      # each edge represents a direct dependency on another pod.
+      #
+      # @param [Hash<String,Array<String>>] all_dependencies
+      #        A hash of pod names to their direct dependencies
+      #
+      # @return [RGL::DirectedAdjacencyGraph] a directed graph
+      def make_graph(all_dependencies)
+        graph = RGL::DirectedAdjacencyGraph.new
+        all_dependencies.each do |source, targets|
+          targets.each { |target| graph.add_edge(source, target) }
+        end
+        graph
+      end
+
+      # Computes and returns all possible paths between a source vertex and a target vertex in a directed graph.
+      # It does this by performing a DFS and, whenever the target is discovered (or re-discovered), the current
+      # DFS stack is captured as one of the possible paths.
+      #
+      # @note Back edges are ignored because the input graph is assumed to be acyclic.
+      #
+      # @param [String] source
+      #        The vertex at which to begin the search.
+      # @param [String] target
+      #        The vertex at which to end the search.
+      # @param [RGL::DirectedAdjacencyGraph] graph
+      #        A directed acyclic graph. The vertices are assumed to be strings (to match the source/target types).
+      #
+      # @return [Array<Array<String>>] a list of all paths from source to target
+      def all_paths(source, target, graph)
+        dfs_stack = [source] # RGL uses recursion for DFS and does not expose a stack, so we build one as we go.
+        all_paths = []
+        visitor = RGL::DFSVisitor.new(graph)
+        visitor.set_tree_edge_event_handler do |_, v|
+          dfs_stack << v
+          all_paths << dfs_stack.dup if v == target
+        end
+        visitor.set_forward_edge_event_handler do |_, v|
+          dfs_stack << v
+          all_paths << dfs_stack.dup if v == target
+          dfs_stack.pop
+        end
+        graph.depth_first_visit(source, visitor) { dfs_stack.pop }
+        all_paths
+      end
+
+      # Converts a list of dependency paths into a graph. The vertices in the paths are
+      # assumed to exist in the given graph.
+      #
+      # @param [RGL::DirectedAdjacencyGraph] graph
+      #        A directed graph of pod dependencies
+      # @param [Array<Array<String>>] all_paths
+      #        A list of paths from one dependency to another
+      #
+      # @return [Array<Array<String>>] a list of all paths from source to target
+      def all_paths_graph(graph, all_paths)
+        all_paths_vertices = all_paths.flatten.to_set
+        graph.vertices_filtered_by { |v| all_paths_vertices.include? v }
+      end
+
+      # Finds and prints all paths from source to target.
+      def find_all_dependency_paths(source, target, graph)
+        all_paths = all_paths(source, target, graph)
+
+        if all_paths.empty?
+          UI.puts "#{source} does not depend on #{target}"
+          return
+        end
+
+        UI.puts "Why does #{source} depend on #{target}?"
+
+        all_paths.each do |path|
+          UI.puts path.join(' ⟶   ')
+        end
+
+        File.open(@to_yaml, 'w') { |file| file.write(all_paths.to_yaml) } if @to_yaml
+        File.open(@to_dot, 'w') { |file| file.write(all_paths_graph(graph, all_paths).to_dot_graph.to_s) } if @to_dot
+      end
+
+      # Finds and prints all pods that depend on source (directly or transitively).
+      def find_reverse_dependencies(source, graph)
+        UI.puts "What depends on #{source}?"
+
+        tree = graph.reverse.bfs_search_tree_from(source)
+        graph = graph.vertices_filtered_by { |v| tree.has_vertex? v }
+        sorted_dependencies = graph.vertices.sort
+        sorted_dependencies.delete(source)
+        sorted_dependencies.each { |dependency| UI.puts dependency }
+
+        File.open(@to_yaml, 'w') { |file| file.write(sorted_dependencies.to_s) } if @to_yaml
+        File.open(@to_dot, 'w') { |file| file.write(graph.to_dot_graph.to_s) } if @to_dot
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: cocoapods-why
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Trevor Harmon
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-06-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+- !ruby/object:Gem::Dependency
+  name: cocoapods
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rgl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+description: In CocoaPods projects with a large number of dependencies, the reason
+  why a particular pod has a transitive dependency on some other pod (possibly one
+  you do not want) is not always clear. This plugin adds a "why" command that shows
+  all paths between the two pods, showing exactly how the two pods are related.
+email:
+- trevorh@squareup.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CONTRIBUTING.md
+- LICENSE
+- README.md
+- lib/cocoapods_plugin.rb
+- lib/cocoapods_why.rb
+- lib/pod/command/why.rb
+homepage: https://github.com/square/cocoapods-why
+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: []
+rubygems_version: 3.0.4
+signing_key: 
+specification_version: 4
+summary: Shows why one CocoaPod depends on another
+test_files: []