licensed 3.1.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9411b608edb8210d926f1c927bcaa65e396eac39dbf6300b946e842a33071a23
-  data.tar.gz: a4dd2527919e79c111107482233945f476df72d9f282431abf99f40a3516b221
+  metadata.gz: 46db33bf2c824a144fbe5a85acfef469c35faeec69c3afd15a6df0c363025174
+  data.tar.gz: 73e300eaeebd28afed3ded55f60fc24b0fae9d20795ac150322c1b1975052215
 SHA512:
-  metadata.gz: 07f9153972ac85375a1cb8273d9990052a8d13bc3918c0cd7697c7a0686ef31ed45045065b10091b569a53ad0f2494ae32f0cf2392ae937d242b2954af92c0f6
-  data.tar.gz: 90364cc7be14673627b0280b018498a0feffc962b1c48a89094b9503d5743362f99ee0c36d601478b1818b10ee48d5b1ef97bdd120d6fbc7299b55efa9c5278c
+  metadata.gz: 7d487c920e977198ac91f7eeac4fbea8c4c49a326c6d449532a06e206e9472d75276879a6e3247fee7f6e64d87f595300b3c7ee995e8d1d595fb53401888ccec
+  data.tar.gz: 77ac80e1833b1c02cbb67aac8a79422e2af24958f89a577f07a0885fb7c3cbbc71dc61e0d5fb1bd453b58a1e6d8d0c5b47bf65fdf669edec4347012af83363b9

data/.github/workflows/test.yml

@@ -33,7 +33,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        bundler: [ '~> 1.15.0', '~> 1.16.0', '~> 1.17.0', '~> 2.0.0' ]
+        bundler: [ '~> 1.17.0', '~> 2.0.0', '~> 2.1.0', '~> 2.2.0' ]
     steps:
     - uses: actions/checkout@v2
     - name: Set up Ruby
@@ -60,8 +60,8 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ghc: [ '8.2', '8.6', '8.8', '8.10' ]
-        cabal: [ '2.4', '3.0', '3.2' ]
+        ghc: [ '8.6', '8.8', '8.10', '9.0' ]
+        cabal: [ '3.0', '3.2', '3.4' ]
     steps:
     - uses: actions/checkout@v2
     - name: Set up Ruby
@@ -89,7 +89,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        php: [ '7.3', '7.4' ]
+        php: [ '7.4', '8.0' ]
     steps:
     - uses: actions/checkout@v2
     - name: Setup php
@@ -116,7 +116,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby: [ 2.5, 2.6, 2.7 ]
+        ruby: [ 2.6, 2.7, 3.0 ]
     steps:
     - uses: actions/checkout@v2
     - name: Set up Ruby
@@ -165,7 +165,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        go: [ '1.10.x', '1.11.x', '1.12.x', '1.13.x', '1.14.x', '1.15.x' ]
+        go: [ '1.12.x', '1.13.x', '1.14.x', '1.15.x', '1.16.x' ]
     steps:
     - uses: actions/checkout@v2
     - name: Setup go
@@ -187,9 +187,18 @@ jobs:
       run: script/source-setup/go
     - name: Run tests
       run: script/test go
+      env:
+        GO111MODULE: "on"
 
   gradle:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # TODO: the reporting plugin used to gather data is not yet fully compatible with
+        # gradle 7, which is needed for compatibility with Java 16.  after compatibility issues
+        # are resolved, update this matrix list with '16'.
+        # possibly fixed by https://github.com/jk1/Gradle-License-Report/pull/166
+        java: [ '11' ]
     steps:
     - uses: actions/checkout@v2
     - name: Set up Ruby
@@ -197,6 +206,11 @@ jobs:
       with:
         ruby-version: 2.6
     - run: bundle lock
+    - name: Set up Java
+      uses: actions/setup-java@v2
+      with:
+        java-version: ${{ matrix.java }}
+        distribution: adopt
     - uses: actions/cache@v1
       with:
         path: vendor/gems
@@ -230,8 +244,8 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        otp: [21.x, 22.x, 23.x]
-        elixir: [ 1.10.x, 1.11.x ]
+        otp: [22.x, 23.x, 24.x]
+        elixir: [ 1.11.x, 1.12.x ]
     steps:
     - uses: actions/checkout@v2
     - uses: erlef/setup-elixir@v1.6.0
@@ -258,7 +272,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node_version: [ 10, 12, 14, 15 ]
+        node_version: [ 12, 14, 16 ]
     steps:
     - uses: actions/checkout@v2
     - name: Setup node
@@ -283,12 +297,15 @@ jobs:
 
   nuget:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        dotnet: [ '3.1.x', '5.x' ]
     steps:
     - uses: actions/checkout@v2
     - name: Setup dotnet
       uses: actions/setup-dotnet@v1
       with:
-        dotnet-version: 3.1.202
+        dotnet-version: ${{ matrix.dotnet }}
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
@@ -309,7 +326,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python: [ '2.x', '3.x' ]
+        python: [ '3.6', '3.7', '3.8', '3.9' ]
     steps:
     - uses: actions/checkout@v2
     - name: Setup python

data/CHANGELOG.md

@@ -6,6 +6,25 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+## 3.2.0
+
+2021-08-19
+
+### Added
+
+- Application names can be dynamically generated based on the path to the application source  (https://github.com/github/licensed/pull/375)
+
+### Changed
+
+- Updated command documentation (https://github.com/github/licensed/pull/378, https://github.com/github/licensed/pull/380/files)
+- Updated configuration documentation (https://github.com/github/licensed/pull/375)
+- Cache and status commands give additional diagnostic output when using JSON and YAML formatters (https://github.com/github/licensed/pull/378)
+- Status command will give users a link to documentation when compliance checks fail (https://github.com/github/licensed/pull/381)
+
+### Fixed
+
+- The bundler source correctly checks that the path bundler specifies a gem is loaded from is a file (https://github.com/github/licensed/pull/379)
+
 ## 3.1.0
 
 2021-06-16

data/README.md

@@ -37,13 +37,13 @@ See the [v2 migration documentation](./docs/migrations/v2.md) for more info on m
 
 Licensed uses the `libgit2` bindings for Ruby provided by `rugged`. `rugged` requires `cmake` and `pkg-config` which you may need to install before you can install Licensed.
 
-   >  Ubuntu
-
-    sudo apt-get install cmake pkg-config
-
-   >  OS X
+```bash
+# Ubuntu
+sudo apt-get install cmake pkg-config
 
-    brew install cmake pkg-config
+# macOS
+brew install cmake pkg-config
+```
 
 ### With a Gemfile
 
@@ -56,7 +56,7 @@ gem 'licensed', :group => 'development'
 And then execute:
 
 ```bash
-$ bundle
+$> bundle
 ```
 
 ### As an executable
@@ -64,24 +64,27 @@ $ bundle
 Download a package from GitHub and extract the executable.  Executable packages are available for each release starting with version 1.2.0.
 
 ```bash
-$ curl -sSL https://github.com/github/licensed/releases/download/<version>/licensed-<version>-<os>-x64.tar.gz > licensed.tar.gz
-$ tar -xzf licensed.tar.gz
-$ rm -f licensed.tar.gz
-$ ./licensed list
+$> curl -sSL https://github.com/github/licensed/releases/download/<version>/licensed-<version>-<os>-x64.tar.gz > licensed.tar.gz
+$> tar -xzf licensed.tar.gz
+$> rm -f licensed.tar.gz
+$> ./licensed list
 ```
 
 For system wide usage, install licensed to a location on `$PATH`, e.g. `/usr/local/bin`.
 
 ## Usage
 
-- `licensed list`: Output enumerated dependencies only.
-- `licensed cache`: Cache licenses and metadata.
-- `licensed status`: Check status of dependencies' cached licenses.
-- `licensed notices`: Write a `NOTICE` file for each application configuration.
-- `licensed version`: Show current installed version of Licensed. Aliases: `-v|--version`
-- `licensed env`: Output environment information from the licensed configuration.
+### Available commands
+
+See the [commands documentation](./docs/commands) for documentation on available commands, or run `licensed -h` to see all of the current available commands.
 
-See the [commands documentation](./docs/commands.md) for additional documentation, or run `licensed -h` to see all of the current available commands.
+### Configuration options
+
+A configuration file is required for most commands.  See the [configuration file documentation](./docs/configuration.md) for more details on the configuration format and available configuration options.
+
+### Available dependency sources
+
+Licensed can enumerate dependency for many languages, package managers, and frameworks.  See the [sources documentation](./docs/sources) for the list of currently available sources.  Sources can be explicitly enabled and disabled as a [configuration option](./docs/configuration/sources.md).
 
 ### Automation
 
@@ -95,80 +98,22 @@ The [licensed-ci](https://github.com/marketplace/actions/licensed-ci) GitHub Act
 
 The [setup-licensed](https://github.com/marketplace/actions/setup-github-licensed) GitHub Action installs `licensed` to the workflow environment.  See the linked actions for usage and details.
 
-### Configuration
-
-All commands, except `version`, accept a `-c|--config` option to specify a path to a configuration file or directory.
-
-If a directory is specified, `licensed` will look in that directory for a file named (in order of preference):
-1. `.licensed.yml`
-2. `.licensed.yaml`
-3. `.licensed.json`
-
-If the option is not specified, the value will be set to the current directory.
-
-See the [configuration file documentation](./docs/configuration.md) for more details on the configuration format.
-
-### Sources
-
-Dependencies will be automatically detected for all of the following sources by default.
-1. [Bower](./docs/sources/bower.md)
-1. [Bundler](./docs/sources/bundler.md)
-1. [Cabal](./docs/sources/cabal.md)
-1. [Composer](./docs/sources/composer.md)
-1. [Git Submodules (git_submodule)](./docs/sources/git_submodule.md)
-1. [Go](./docs/sources/go.md)
-1. [Go Dep (dep)](./docs/sources/dep.md)
-1. [Gradle](./docs/sources/gradle.md)
-1. [Manifest lists (manifests)](./docs/sources/manifests.md)
-1. [Mix](./docs/sources/mix.md)
-1. [npm](./docs/sources/npm.md)
-1. [NuGet](./docs/sources/nuget.md)
-1. [Pip](./docs/sources/pip.md)
-1. [Pipenv](./docs/sources/pipenv.md)
-1. [Swift](./docs/sources/swift.md)
-1. [Yarn](./docs/sources/yarn.md)
-
-You can disable any of them in the configuration file:
-
-```yml
-sources:
-  bundler: false
-  npm: false
-  bower: false
-  cabal: false
-```
-
 ## Development
 
 To get started after checking out the repo, run
+
 1. `script/bootstrap` to install dependencies
 2. `script/setup` to setup test fixtures.
   - `script/setup -f` will force a clean test fixture environment
-3. `script/cibuild` to run the tests.
+3. `script/cibuild` to run the tests
 
 You can also run `script/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
-#### Adding sources
-
-When adding new dependency sources, ensure that `script/bootstrap` scripting and tests are only run if the required tooling is available on the development machine.
-
-* See `script/bootstrap` for examples of gating scripting based on whether tooling executables are found.
-* Use `Licensed::Shell.tool_available?` when writing test files to gate running a test suite when tooling executables aren't available.
-```ruby
-if Licensed::Shell.tool_available?('bundle')
-  describe Licensed::Source::Bundler do
-    ...
-  end
-end
-```
-
-See the [documentation on adding new sources](./docs/adding_a_new_source.md) for more information.
-
-#### Adding Commands
+### Adding a new source
 
-See the [documentation on commands](./docs/commands.md) for information about adding a new CLI command.
+See the [documentation on adding new sources](./docs/adding_a_new_source.md) for detailed information on what's required to add a new dependency source enumerator.
 
 ## Contributing
 

data/docs/adding_a_new_source.md

@@ -4,13 +4,15 @@
 
 Dependency enumerators inherit and override the [`Licensed::Sources::Source`](../lib/licensed/sources/source.rb) class.
 
-#### Required method overrides
+### Required method overrides
+
 1. `Licensed::Sources::Source#enabled?`
    - Returns whether dependencies can be enumerated in the current environment.
 2. `Licensed::Sources::Source#enumerate_dependencies`
    - Returns an enumeration of `Licensed::Dependency` objects found which map to the dependencies of the current project.
 
-#### Optional method overrides
+### Optional method overrides
+
 1. `Licensed::Sources::Source.type`
    - Returns the name of the current dependency enumerator as it is found in a licensed configuration file.
 
@@ -22,12 +24,13 @@ whether `Licensed::Source::Sources#enumerate_dependencies` should be called on t
 Determining whether dependencies should be enumerated depends on whether all the tools or files needed to find dependencies are present.
 For example, to enumerate `npm` dependencies the `npm` CLI tool must be found with `Licensed::Shell.tool_available?` and a `package.json` file needs to exist in the licensed app's configured [`source_path`](./configuration.md#configuration-paths).
 
-#### Gating functionality when required tools are not available.
+### Gating functionality when required tools are not available.
 
 When adding new dependency sources, ensure that `script/bootstrap` scripting and tests are only run if the required tooling is available on the development machine.
 
-* See `script/bootstrap` for examples of gating scripting based on whether tooling executables are found.
-* Use `Licensed::Shell.tool_available?` when writing test files to gate running a test suite when tooling executables aren't available.
+- See `script/bootstrap` for examples of gating scripting based on whether tooling executables are found.
+- Use `Licensed::Shell.tool_available?` when writing test files to gate running a test suite when tooling executables aren't available.
+
 ```ruby
 if Licensed::Shell.tool_available?('bundle')
   describe Licensed::Source::Bundler do
@@ -47,11 +50,11 @@ Relying on external tools always has a risk that the tool could change.  It's ge
 or other implementation details as these could change over time.  CLI tools that provides the necessary information are generally preferred
 as they will more likely have requirements for backwards compatibility.
 
-#### Creating dependency objects
+### Creating dependency objects
 
 Creating a new `Licensed::Dependency` object requires name, version, and path arguments.  Dependency objects optionally accept a path to use as search root when finding licenses along with any other metadata that is useful to identify the dependency.
 
-##### `Licensed::Dependency` arguments
+#### `Licensed::Dependency` arguments
 
 1. name (required)
    - The name of the dependency. Together with the version, this should uniquely identify the dependency.
@@ -71,7 +74,7 @@ Creating a new `Licensed::Dependency` object requires name, version, and path ar
 6. errors (optional)
   - Any errors found when loading dependency information.
 
-##### Creating specialized Dependency objects
+#### Creating specialized Dependency objects
 
 `Licensed::Dependency` objects inherit from `Licensee::Projects::FsProject` and can override or extend the default `Licensee` behavior to find files for a dependency.
 

data/docs/commands/README.md

@@ -0,0 +1,59 @@
+# Commands
+
+Run `licensed -h` to see help content for running licensed commands.
+
+- [cache](cache.md)
+- [env](env.md)
+- [list](list.md)
+- [migrate](migrate.md)
+- [notices](notices.md)
+- [status](status.md)
+- [version](verison.md)
+
+Most commands accept a `-c`/`--config` option to specify a path to a configuration file or directory. If a directory is specified, `licensed` will look in that directory for a file named (in order of preference):
+
+1. `.licensed.yml`
+2. `.licensed.yaml`
+3. `.licensed.json`
+
+If the option is not specified, the value will be set to the current directory.
+
+## Adding a new command
+
+### Implement new `Command` class
+
+Licensed commands inherit and override the [`Licensed::Sources::Command`](../lib/licensed/commands/command.rb) class.
+
+### Required method overrides
+
+1. `Licensed::Commands::Command#evaluate_dependency`
+   - Runs a command execution on an application dependency.
+
+The `evaluate_dependency` method should contain the specific command logic.  This method has access to the application configuration, dependency source enumerator and dependency currently being evaluated as well as a reporting hash to contain information about the command execution.
+
+### Optional method overrides
+
+The following methods break apart the different levels of command execution.  Each method wraps lower levels of command execution in a corresponding reporter method.
+
+1. `Licensed::Commands::Command#run`
+   - Runs `run_app` for each application configuration found.  Wraps the execution of all applications in `Reporter#report_run`.
+2. `Licensed::Commands::Command#run_app`
+   - Runs `run_source` for each dependency source enumerator enabled for the application configuration.  Wraps the execution of all sources in `Reporter#report_app`.
+3. `Licensed::Commands::Command#run_source`
+   - Runs `run_dependency` for each dependency found in the source.  Wraps the execution of all dependencies in `Reporter#report_source`.
+4. `Licensed::Commands::Command#run_dependency`
+   - Runs `evaluate_dependency` for the dependency.  Wraps the execution of all dependencies in `Reporter#report_dependency`.
+
+As an example, `Licensed::Commands::Command#run_app` calls `Reporter#report_app` to wrap every call to `Licensed::Commands::Command#run_source`.
+
+### Specifying additional report data
+
+The `run` methods can be overridden and pass a block to `super` to provide additional reporting data or functionality.
+
+```ruby
+def run_app(app)
+  super do |report|
+    report["my_app_data"] = true
+  end
+end
+```

data/docs/commands/cache.md

@@ -0,0 +1,35 @@
+# `licensed cache`
+
+The cache command finds all dependencies and ensures that each dependency has an up-to-date cached record.
+
+Dependency records will be saved if:
+
+1. The `force` option is set
+2. No cached record is found
+3. The cached record's version is different than the current dependency's version
+   - If the cached record's license text contents matches the current dependency's license text then the `license` metadata from the cached record is retained for the new saved record.
+
+After the cache command is run, any cached records that don't match up to a current application dependency will be deleted.
+
+## Options
+
+- `--config`/`-c`: the path to the licensed configuration file
+   - default value: `./.licensed.yml`
+- `--sources`/`-s`: runtime filter on which dependency sources are run.  Sources must also be enabled in the licensed configuration file.
+   - default value: not set, all configured sources
+- `--format`/`-f`: the output format
+   - default value: `yaml`
+- `--force`: if set, forces all dependency metadata files to be recached
+   - default value: not set
+
+## Reported Data
+
+The following data is reported for each dependency when the YAML or JSON report formats are used
+
+- name: the licensed recognized name for the dependency including the app and source name
+   - e.g. the full name for the `thor` bundler dependency used by this tool is `licensed.bundler.thor`
+- cached: true when the dependency's cached metadata file was updated, false otherwise
+- version: the version of the enumerated dependency
+- license: the dependency's SPDX license identifier
+- filename: the full path on disk to the dependency's cached metadata file, if available
+- warnings: any warning messages encountered while enumerating and caching dependency metadata, if available