# Commands

Run `licensed -h` to see help content for running licensed commands.

## `list`

Running the list command finds the dependencies for all sources in all configured applications.  No additional actions are taken on each dependency.

## `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.

## `status`

The status command finds all dependencies and checks whether each dependency has a valid cached record.

A dependency will fail the status checks if:
1. No cached record is found
2. The cached record's version is different than the current dependency's version
3. The cached record doesn't contain any license text
4. The cached record's `license` metadata doesn't match an `allowed` license from the dependency's application configuration.

## `version`

Displays the current licensed version.

# 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`.

##### Overriding optional methods

The `run` methods can be overridden to provide additional reporting data or functionality.  Overriding a method should call the original method with a block for the additional logic.

```ruby
def run_app(app)
  super do |report|
    result = yield report
    
    # do other thing
    call_additional_functionality(app)
    
    # add reporting information
    report["result"] = result
    
    # return the result
    result
  end
end
```