licensed 3.0.0 → 3.2.1

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/docs/configuration.md

@@ -2,75 +2,12 @@
 
 A configuration file specifies the details of enumerating and operating on license metadata for apps.
 
-Configuration can be specified in either YML or JSON formats.  Examples below are given in YML.
+Configuration can be specified in either YML or JSON formats, with examples given in YML.  The example
+below describes common configuration values and their purposes.  See [configuration options documentation](./configuration)
+for in depth information.  
 
-## Configuration Paths
-
-`licensed` requires a path to enumerate dependencies at (`source_path`) and a path to store cached metadata (`cache_path`).
-
-To determine these paths across multiple environments where absolute paths will differ, a known root path is needed to evaluate relative paths against.
-In using a root, relative source and cache paths can be specified in the configuration file.
-
-When using a configuration file, the root property can be set as either a path that can be expanded from the configuration file directory using `File.expand_path`, or the value `true` to use the configuration file directory as the root.
-
-When creating a `Licensed::Dependency` manually with a `root` property, the property must be an absolute path - no path expansion will occur.
-
-If a root path is not specified, it will default to using the following, in order of precedence
-1. the root of the local git repository, if run inside a git repository
-2. the current directory
-
-### Source path glob patterns
-
-The `source_path` property can use a glob path to share configuration properties across multiple application entrypoints.
-
-For example, there is a common pattern in Go projects to include multiple executable entrypoints under folders in `cmd`.  Using a glob pattern allows users to avoid manually configuring and maintaining multiple licensed application `source_path`s.  Using a glob pattern will also ensure that any new entrypoints matching the pattern are automatically picked up by licensed commands as they are added.
-
-```yml
-sources:
-  go: true
-
-# treat all directories under `cmd` as separate apps
-source_path: cmd/*
-```
-
-Glob patterns are syntactic sugar for, and provide the same functionality as, manually specifying multiple `source_path` values. See the instructions on [specifying multiple apps](./#specifying-multiple-apps) below for additional considerations when using multiple apps.
-
-## Restricting sources
-
-The `sources` configuration property specifies which sources `licensed` will use to enumerate dependencies.
-By default, `licensed` will generally 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.
-
-Be aware that this configuration is separate from an individual sources `#enabled?` method, which determines
-whether the source is valid for the current project.  Even if a source is enabled in the configuration
-it may still determine that it can't enumerate dependencies for a project.
+Additionally, some dependency sources have their own specific configuration options.  See the [source documentation](./sources) for details.
 
-```yml
-sources:
-  bower: true
-  bundler: false
-```
-
-`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
-```yml
-sources:
-  bower: false
-  # all other sources are enabled by default since there are no sources set to true
-```
-3. If any sources are set to true, any unconfigured sources are disabled
-```yml
-sources:
-  bower: true
-  # all other sources are disabled by default because a source was set to true
-```
-
-## Applications
-
-What is an "app"?  In the context of `licensed`, an app is a combination of a source path and a cache path.
-
-Configuration can be set up for single or multiple applications in the same repo.  There are a number of settings available for each app:
 ```yml
 # If not set, defaults to the directory name of `source_path`
 name: 'My application'
@@ -129,100 +66,11 @@ reviewed:
   bower:
   - classlist # public domain
   - octicons
-```
-
-### Specifying a single app
-To specify a single app, either include a single app with `source_path` in the `apps` configuration, or remove the `apps` setting entirely.
-
-If the configuration does not contain an `apps` value, the root configuration will be used as an app definition.  In this scenario, the `source_path` is not a required value and will default to the directory that `licensed` was executed from.
-
-If the configuration contains an `apps` value with a single app configuration, `source_path` must be specified.  Additionally, the applications inherited `cache_path` value will contain the application name.  See [Inherited cache_path values](#inherited_cache_path_values)
-
-### Specifying multiple apps
-The configuration file can specify multiple source paths to enumerate metadata, each with their own configuration.
-
-Nearly all configuration settings can be inherited from root configuration to app configuration.  Only `source_path` is required to define an app.
 
-Here are some examples:
-
-#### Inheriting configuration
-```yml
-sources:
-  go: true
-  bundler: false
-
-ignored:
-  bundler:
-    - some-internal-gem
-
-reviewed:
-  bundler:
-    - bcrypt-ruby
-
-cache_path: 'path/to/cache'
-apps:
-  - source_path: 'path/to/app1'
-  - source_path: 'path/to/app2'
-    sources:
-      bundler: true
-      go: false
-```
-
-In this example, two apps have been declared.  The first app, with `source_path` `path/to/app1`, inherits all configuration settings from the root configuration.  The second app, with `source_path` `path/to/app2`, overrides the `sources` configuration and inherits all other settings.
-
-#### Default app names
-An app will not inherit a name set from the root configuration.  If not provided, the `name` value will default to the directory name from `source_path`.
-```yml
+# A single configuration file can be used to enumerate dependencies for multiple
+# projects.  Each configuration is referred to as an "application" and must include
+# a source path, at a minimum
 apps:
-  - source_path: 'path/to/app1'
-  - source_path: 'path/to/app2'
+  - source_path: path/to/application1
+  - source_path: path/to/application2
 ```
-
-In this example, the apps have names of `app1` and `app2`, respectively.
-
-#### Inherited cache_path values
-When an app inherits a `cache_path` from the root configuration, it will automatically append it's name to the end of the path to separate it's metadata from other apps.  To force multiple apps to use the same path to cached metadata, explicitly set the `cache_path` value for each app.
-```yml
-cache_path: 'path/to/cache'
-apps:
-  - source_path: 'path/to/app1'
-    name: 'app1'
-  - source_path: 'path/to/app2'
-    name: 'app2'
-  - source_path: 'path/to/app3'
-    name: 'app3'
-    cache_path: 'path/to/app3/cache'
-```
-
-In this example `app1` and `app2` have `cache_path` values of `path/to/cache/app1` and `path/to/cache/app2`, respectively.  `app3` has an explicit path set to `path/to/app3/cache`
-
-```yml
-apps:
-  - source_path: 'path/to/app1'
-```
-
-In this example, the root configuration will contain a default cache path of `.licenses`.  `app1` will inherit this value and append it's name, resulting in a cache path of `.licenses/app1`.
-
-### Sharing caches between apps
-
-Dependency caches can be shared between apps by setting the same cache path on each app.
-
-```yaml
-apps:
-  - source_path: "path/to/app1"
-    cache_path: ".licenses/apps"
-  - source_path: "path/to/app2"
-    cache_path: ".licenses/apps"
-```
-
-When using a source path with a glob pattern, the apps created from the glob pattern can share a dependency by setting an explicit cache path and setting `shared_cache` to true.
-
-```yaml
-source_path: "path/to/apps/*"
-cache_path: ".licenses/apps"
-shared_cache: true
-```
-
-## Source specific configuration
-
-See the [source documentation](./sources) for details on any source specific configuration.

data/docs/sources/swift.md

@@ -0,0 +1,4 @@
+# Swift
+
+The Swift source uses `swift package` subcommands
+to enumerate dependencies and properties.

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