licensed 3.1.0 → 3.2.0

data/docs/configuration/configuration_root.md

@@ -0,0 +1,27 @@
+# Configuration root
+
+**Key**: root  
+**Default value**:
+
+   1. the root of the local git repository, if run inside a git repository
+   1. the directory that `licensed` is run from
+
+An application's root path is used as the base for any relative configuration paths in the application.
+
+From a configuration file, the root value can be specified as one of the following.  Path string values can contain special path characters.
+
+- a relative path from the configuration file location
+- an absolute path
+- `true` to use the configuration file's directory as the root
+
+When creating a `Licensed::AppConfiguration` manually with a `root` property, the property must be an absolute path - no path expansion will occur.
+
+```yml
+root: path/from/configuration
+# or
+root: /absolute/path/to/root
+# or
+root: ~/path/from/home/to/root
+# or
+root: true
+```

data/docs/configuration/configuring_multiple_apps.md

@@ -0,0 +1,58 @@
+# Configuring multiple application definitions
+
+**Key**: apps
+**Required**: false
+
+The configuration file can specify multiple source paths to enumerate metadata, each with their own configuration by using the `apps` key.
+Each source path and any additional configuration make up an "application".  Root configuration settings are inherited into each application,
+allowing applications to share a common configuration and reducing the overall size of the configuration file.
+
+When the apps key is not given, the root configuration is treated as a single application.
+
+```yml
+apps:
+  # application definition for "go-application"
+  - source_path: path/to/go-application
+    sources:
+      go: true
+    allowed:
+      - mit
+
+  # application definition for "ruby-application"
+  - source_path: path/to/ruby-application
+    sources:
+      bundler: true
+    allowed:
+      - bsd-3-clause
+```
+
+## Inheriting configuration
+
+Applications inherit all root configuration settings.  Inherited settings will be overridden by any configuration set directly on the application definition.
+
+In this example, two apps have been declared.  The first app, with `source_path: path/to/application1`, inherits all configuration settings from the root configuration.  The second app, with `source_path: path/to/application2`, overrides the `sources` configuration and inherits all other settings.
+
+```yml
+sources:
+  go: true
+  bundler: false
+
+ignored:
+  bundler:
+    - some-internal-gem
+
+reviewed:
+  bundler:
+    - bcrypt-ruby
+
+cache_path: 'path/to/cache'
+apps:
+  # inherits all settings from the root configuration
+  - source_path: 'path/to/application1'
+
+  # inherits all settings except for "sources" from the root configuration
+  - source_path: 'path/to/application2'
+    sources:
+      bundler: true
+      go: false
+```

data/docs/configuration/dependency_source_enumerators.md

@@ -0,0 +1,28 @@
+# Specifying dependency sources to use in an application
+
+**Key**: sources  
+**Required**: false  
+**Default value**: All sources enabled
+
+The sources configuration property specifies which sources `licensed` will use to enumerate dependencies.
+By default, `licensed` will try to enumerate dependencies from all sources.  As a result,
+the configuration property should be used to explicitly disable sources rather than to enable a particular source.
+
+This configuration value does not guarantee that a source will enumerate dependencies.  Each
+configured source's `enabled?` method must return true for licensed to pull dependency information.
+
+`licensed` determines which sources will try to enumerate dependencies based on the following rules:
+
+1. If no sources are configured, all sources are enabled
+2. If no sources are set to true, any unconfigured sources are enabled
+3. If any sources are set to true, any unconfigured sources are disabled
+
+```yml
+# all other sources are enabled by default since there are no sources set to true
+sources:
+  bower: false
+
+# all other sources are disabled by default because a source was set to true
+sources:
+  bower: true
+```

data/docs/configuration/ignoring_dependencies.md

@@ -0,0 +1,19 @@
+# Ignoring dependencies
+
+**Key**: ignored
+**Default value**: none
+
+This configuration property is used to fully ignore a dependency during all `licensed` commands.  Any dependency on this list will not
+be enumerated, or have its metadata cached or checked for compliance.  This is intended for dependencies that do not require attribution
+or compliance checking - internal or 1st party dependencies, or dependencies that do not ship with the product such as test frameworks.
+
+The ignored dependency list is organized based on the dependency source type - `bundler`, `go`, etc.  Add a dependency's metadata identifier to the appropriate source type sub-property to cause `licensed` to no longer take action on the dependency.  Glob patterns can be used to identify multiple internal dependencies without having to manage a large list.
+
+```yml
+ignored:
+  bundler:
+    - my-internal-gem
+    - my-first-party-gem
+  go:
+    - github.com/me/my-repo/**/*
+```

data/docs/configuration/metadata_cache.md

@@ -0,0 +1,106 @@
+# Dependency metadata cache
+
+**Key**: cache_path  
+**Default value**: .licenses
+
+The cache path is the root directory where `licensed` will write cached metadata files for each dependency.
+By default, files will be written to a folder under the cache path in a structure like:
+
+```text
+<cache path>
+|_<source name>
+  |_<dependency identifier>.dep.yml
+```
+
+Cache paths can be given as an absolute or relative path and can contain special path characters
+
+```yml
+cache_path: relative/path/to/cache
+# or
+cache_path: /absolute/path/to/cache
+# or
+cache_path: ~/path/from/home/to/cache
+```
+
+## Configuring caches for multiple applications
+
+When multiple applications are specified in a configuration file caches can be shared, inherited and explicitly configured.
+Unless otherwise specified, preference is given based on the locality and intention of the configuration options.
+
+1. explicitly configured cache paths are preferred to inherited or shared cache paths
+2. shared cache paths are preferred to inherited cache paths
+3. cache paths that are not otherwise set by an application will be inherited from the root configuration
+
+### Explicit cache usage for multiple applications
+
+Individual applications in a multi-application configuration can explicitly set cache paths.
+
+```yml
+apps:
+  - source_path: path/to/application1
+    cache_path: path/to/application1/.licenses
+  - source_path: path/to/application2
+    cache_path: path/to/application2/.licenses
+```
+
+### Sharing a single cache for multiple applications
+
+Sharing a cache across multiple applications is possible by setting `cache_path: <path>` and `shared_cache: true` at the root level.
+Individual applications can opt out of sharing a cache by explicitly setting a cache path.
+
+```yml
+shared_cache: true
+cache_path: .cache/shared
+apps:
+  # application1 and application2 will share a cache at .cache/shared
+  - source_path: path/to/application1
+  - source_path: path/to/application2
+  # application3 will use a separate cache at .cache/application3
+  - source_path: path/to/application3
+    cache_path: .cache/application3
+```
+
+This is equivalent to explicitly configuring the same cache for many applications
+
+```yaml
+apps:
+  - source_path: "path/to/application1"
+    cache_path: ".cache/shared"
+  - source_path: "path/to/application2"
+    cache_path: ".cache/shared"
+```
+
+Using the `shared_cache` key is primarily useful when specifying `source_path` as a glob pattern.
+
+```yml
+shared_cache: true
+cache_path: .cache/shared
+source_path: path/to/*
+```
+
+### Inheriting cache usage from the root configuration
+
+When not otherwise specified, applications will inherit a cache path from the root configuration.
+If the root configuration does not explicitly set a cache path value, the default cache path value is used.
+
+Inherited cache paths are treated as the root location for each application's metadata cache.  Each application
+will store metadata in a named subdirectory of the root location to avoid file path clashes between
+applications.
+
+```yml
+# optional.  if not specified, the default value `.licenses` will be used
+cache_path: .cache
+apps:
+  - source_path: path/to/application1
+  - source_path: path/to/application2
+```
+
+```text
+.cache
+|_application1
+  |_<source type>
+    |_<dependency identifier>.dep.yml
+|_application2
+  |_<source type>
+    |_<dependency identifier>.dep.yml
+```

data/docs/configuration/reviewing_dependencies.md

@@ -0,0 +1,18 @@
+# Reviewing dependencies
+
+**Key**: reviewed
+**Default value**: none
+
+Sometimes your projects will use a dependency with an OSS license that you don't want to globally allow but can use with individual review.
+The list of reviewed dependencies is meant to cover this scenario and will prevent the status command from raising an error for
+a dependency with a license not on the allowed list.
+
+The reviewed dependency list is organized based on the dependency source type - `bundler`, `go`, etc.  Add a dependency's metadata identifier to the appropriate source type sub-property to cause `licensed` to ignore license compliance failures.  Glob patterns can be used to identify multiple internal dependencies without having to manage a large list.
+
+_NOTE: marking a dependency as reviewed will not prevent licensed from raising an error on missing license information._
+
+```yml
+reviewed:
+  bundler:
+    - gem-using-unallowed-license
+```

data/lib/licensed.rb

@@ -6,6 +6,7 @@ require "licensed/dependency"
 require "licensed/git"
 require "licensed/sources"
 require "licensed/configuration"
+require "licensed/report"
 require "licensed/reporters"
 require "licensed/commands"
 require "licensed/ui/shell"

data/lib/licensed/cli.rb

@@ -20,12 +20,12 @@ module Licensed
     end
 
     desc "status", "Check status of dependencies' cached licenses"
-    method_option :format, enum: ["yaml", "json"],
-      desc: "Output format"
     method_option :config, aliases: "-c", type: :string,
       desc: "Path to licensed configuration file"
     method_option :sources, aliases: "-s", type: :array,
       desc: "Individual source(s) to evaluate.  Must also be enabled via configuration."
+    method_option :format, aliases: "-f", enum: ["yaml", "json"],
+      desc: "Output format"
     def status
       run Licensed::Commands::Status.new(config: config), sources: options[:sources], reporter: options[:format]
     end

data/lib/licensed/commands/cache.rb

@@ -11,6 +11,8 @@ module Licensed
         Licensed::Reporters::CacheReporter.new
       end
 
+      protected
+
       # Run the command.
       # Removes any cached records that don't match a current application
       # dependency.
@@ -18,20 +20,15 @@ module Licensed
       # options - Options to run the command with
       #
       # Returns whether the command was a success
-      def run(**options)
-        begin
-          result = super
+      def run_command(report)
+        super do |result|
           clear_stale_cached_records if result
-
-          result
-        ensure
-          cache_paths.clear
-          files.clear
         end
+      ensure
+        cache_paths.clear
+        files.clear
       end
 
-      protected
-
       # Run the command for all enumerated dependencies found in a dependency source,
       # recording results in a report.
       # Enumerating dependencies in the source is skipped if a :sources option
@@ -41,17 +38,12 @@ module Licensed
       # source - A dependency source enumerator
       #
       # Returns whether the command succeeded for the dependency source enumerator
-      def run_source(app, source)
-        super do |report|
-          if Array(options[:sources]).any? && !options[:sources].include?(source.class.type)
-            report.warnings << "skipped source"
-            next :skip
-          end
+      def run_source(app, source, report)
+        # add the full cache path to the list of cache paths
+        # that should be cleaned up after the command run
+        cache_paths << app.cache_path.join(source.class.type)
 
-          # add the full cache path to the list of cache paths
-          # that should be cleaned up after the command run
-          cache_paths << app.cache_path.join(source.class.type)
-        end
+        super
       end
 
       # Cache dependency record data.
@@ -70,6 +62,12 @@ module Licensed
 
         filename = app.cache_path.join(source.class.type, "#{dependency.name}.#{DependencyRecord::EXTENSION}")
         cached_record = Licensed::DependencyRecord.read(filename)
+
+        report["cached"] = false
+        report["license"] = cached_record["license"] if cached_record
+        report["filename"] = filename.to_s
+        report["version"] = dependency.version
+
         if options[:force] || save_dependency_record?(dependency, cached_record)
           if dependency.record.matches?(cached_record)
             # use the cached license value if the license text wasn't updated
@@ -82,6 +80,7 @@ module Licensed
 
           dependency.record.save(filename)
           report["cached"] = true
+          report["license"] = dependency.record["license"]
         end
 
         if !dependency.exist?

data/lib/licensed/commands/command.rb

@@ -18,23 +18,12 @@ module Licensed
       def run(**options)
         @options = options
         @reporter = create_reporter(options)
-        begin
-          result = reporter.report_run(self) do |report|
-            # allow additional report data to be given by commands
-            if block_given?
-              next true if (yield report) == :skip
-            end
-
-            config.apps.sort_by { |app| app["name"] }
-                       .map { |app| run_app(app) }
-                       .all?
-          end
-        ensure
-          @options = nil
-          @reporter = nil
-        end
 
-        result
+        command_report = Licensed::Report.new(name: nil, target: self)
+        run_command(command_report)
+      ensure
+        @options = nil
+        @reporter = nil
       end
 
       # Creates a reporter to use during a command run
@@ -64,36 +53,65 @@ module Licensed
 
       protected
 
+      # Run the command for all application configurations
+      #
+      # report - A Licensed::Report object for this command
+      #
+      # Returns whether the command succeeded
+      def run_command(report)
+        reporter.begin_report_command(self, report)
+        apps = config.apps.sort_by { |app| app["name"] }
+        results = apps.map do |app|
+          app_report = Licensed::Report.new(name: app["name"], target: app)
+          report.reports << app_report
+          run_app(app, app_report)
+        end
+
+        result = results.all?
+
+        yield(result) if block_given?
+
+        result
+      ensure
+        reporter.end_report_command(self, report)
+      end
+
       # Run the command for all enabled sources for an application configuration,
       # recording results in a report.
       #
       # app - An application configuration
+      # report - A report object for this application
       #
       # Returns whether the command succeeded for the application.
-      def run_app(app)
-        reporter.report_app(app) do |report|
-          # ensure the app source path exists before evaluation
-          if !Dir.exist?(app.source_path)
-            report.errors << "No such directory #{app.source_path}"
-            next false
-          end
+      def run_app(app, report)
+        reporter.begin_report_app(app, report)
 
-          Dir.chdir app.source_path do
-            begin
-              # allow additional report data to be given by commands
-              if block_given?
-                next true if (yield report) == :skip
-              end
-
-              app.sources.select(&:enabled?)
-                         .sort_by { |source| source.class.type }
-                         .map { |source| run_source(app, source) }.all?
-            rescue Licensed::Shell::Error => err
-              report.errors << err.message
-              false
-            end
+        # ensure the app source path exists before evaluation
+        if !Dir.exist?(app.source_path)
+          report.errors << "No such directory #{app.source_path}"
+          return false
+        end
+
+        Dir.chdir app.source_path do
+          sources = app.sources.select(&:enabled?)
+                               .sort_by { |source| source.class.type }
+          results = sources.map do |source|
+            source_report = Licensed::Report.new(name: [report.name, source.class.type].join("."), target: source)
+            report.reports << source_report
+            run_source(app, source, source_report)
           end
+
+          result = results.all?
+
+          yield(result) if block_given?
+
+          result
         end
+      rescue Licensed::Shell::Error => err
+        report.errors << err.message
+        false
+      ensure
+        reporter.end_report_app(app, report)
       end
 
       # Run the command for all enumerated dependencies found in a dependency source,
@@ -101,27 +119,37 @@ module Licensed
       #
       # app - The application configuration for the source
       # source - A dependency source enumerator
+      # report - A report object for this source
       #
       # Returns whether the command succeeded for the dependency source enumerator
-      def run_source(app, source)
-        reporter.report_source(source) do |report|
-          begin
-            # allow additional report data to be given by commands
-            if block_given?
-              next true if (yield report) == :skip
-            end
-
-            source.dependencies.sort_by { |dependency| dependency.name }
-                               .map { |dependency| run_dependency(app, source, dependency) }
-                               .all?
-          rescue Licensed::Shell::Error => err
-            report.errors << err.message
-            false
-          rescue Licensed::Sources::Source::Error => err
-            report.errors << err.message
-            false
-          end
+      def run_source(app, source, report)
+        reporter.begin_report_source(source, report)
+
+        if !sources_overrides.empty? && !sources_overrides.include?(source.class.type)
+          report.warnings << "skipped source"
+          return true
         end
+
+        dependencies = source.dependencies.sort_by { |dependency| dependency.name }
+        results = dependencies.map do |dependency|
+          dependency_report = Licensed::Report.new(name: [report.name, dependency.name].join("."), target: dependency)
+          report.reports << dependency_report
+          run_dependency(app, source, dependency, dependency_report)
+        end
+
+        result = results.all?
+
+        yield(result) if block_given?
+
+        result
+      rescue Licensed::Shell::Error => err
+        report.errors << err.message
+        false
+      rescue Licensed::Sources::Source::Error => err
+        report.errors << err.message
+        false
+      ensure
+        reporter.end_report_source(source, report)
       end
 
       # Run the command for a dependency, evaluating the dependency and
@@ -131,27 +159,27 @@ module Licensed
       # app - The application configuration for the dependency
       # source - The dependency source enumerator for the dependency
       # dependency - An application dependency
+      # report - A report object for this dependency
       #
       # Returns whether the command succeeded for the dependency
-      def run_dependency(app, source, dependency)
-        reporter.report_dependency(dependency) do |report|
-          if dependency.errors?
-            report.errors.concat(dependency.errors)
-            return false
-          end
+      def run_dependency(app, source, dependency, report)
+        reporter.begin_report_dependency(dependency, report)
 
-          begin
-            # allow additional report data to be given by commands
-            if block_given?
-              next true if (yield report) == :skip
-            end
-
-            evaluate_dependency(app, source, dependency, report)
-          rescue Licensed::DependencyRecord::Error, Licensed::Shell::Error => err
-            report.errors << err.message
-            false
-          end
+        if dependency.errors?
+          report.errors.concat(dependency.errors)
+          return false
         end
+
+        result = evaluate_dependency(app, source, dependency, report)
+
+        yield(result) if block_given?
+
+        result
+      rescue Licensed::DependencyRecord::Error, Licensed::Shell::Error => err
+        report.errors << err.message
+        false
+      ensure
+        reporter.end_report_dependency(dependency, report)
       end
 
       # Evaluate a dependency for the command.  Must be implemented by a command implementation.
@@ -165,6 +193,10 @@ module Licensed
       def evaluate_dependency(app, source, dependency, report)
         raise "`evaluate_dependency` must be implemented by a command"
       end
+
+      def sources_overrides
+        @sources_overrides = Array(options[:sources])
+      end
     end
   end
 end