> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# moneyforward/dscar

Delta Static Code Analysis Reports running on CircleCI

This Orb calculates the difference between two static code analysis results.
However, the format of the static code analysis result must be Checkstyle XML.
Using this Orb, you can get the static code analysis result for the update
difference between HEAD branch and its BASE branch.


## Commands

### analyze

Analyze code statically

| Parameter | Type | Default | Description |
|---|---|---|---|
| `analysis-arguments` | string |  | Arguments of analysis command |
| `analysis-command` | string | true | The command used for analysis |
| `analysis-name` | string | true | Analysis name |
| `analysis-results-path` | string |  | Specify the path to save the analysis results if you need to change it (default: /tmp/dscar/analysis-results) |
| `error-pattern` | string | (?!) | Specify the pattern if you want to detect analyzing errors from the standard error |
| `exit-code-threshold` | integer | 124 | Specify the upper limit of the exit code that is regarded as normal termination |
| `footer-arguments` | string |  | Arguments of footer command |
| `footer-command` | string | true | The command used for footer of analysis result |
| `header-arguments` | string |  | Arguments of header command |
| `header-command` | string | true | The command used for header of analysis result |
| `ignore-exit-code` | boolean | false | Specify true if you want the exit code of the analysis step to always return 0. |
| `max-procs` | integer | 1 | Specify the maximum number of processes to run at the same time |
| `no-output-timeout` | string | 10m | Elapsed time the command can run without output. The string is a decimal with unit suffix, such as “20m”, “1.25h”, “5s” |
| `patterns-to-exclude` | string |  | Specify patterns to exclude by regular expression (Multiple patterns can be specified by separating them with line feed) |
| `patterns-to-include` | string | .* | Specify patterns to include by regular expression (Multiple patterns can be specified by separating them with line feed) |
| `prepare` | steps |  | Specify the required steps before analysis if necessary |
| `redirecting-output` | enum | /dev/stdout | Specify "/dev/null" if you do not want to display the analysis results on the standard output |
| `should-find` | enum | false | Specify true if you want to find for analysis targets |
| `starting-points` | string | . | Specify the path of starting to search for files to analyze (Multiple paths can be specified by separating them with line feed) |
| `step-name` | string | Analyze code statically | Specify a analysis step name for this command, if desired |
| `transformation-arguments` | string |  | Arguments of transformation command |
| `transformation-command` | string | cat | The command used for transformation |

### analyze-and-evaluate

Analyze the code statically and then evaluate the result

| Parameter | Type | Default | Description |
|---|---|---|---|
| `analyze` | steps | analyze | Specify analysis steps |
| `circle_compare_url-path` | string |  | Specify the path of `CIRCLE_COMPARE_URL.txt` if you are using `iynere/compare-url` orb |
| `test-results-path` | string | /tmp/test-results | Specify the value of the path parameter in the store_test_results step if you need to change it |
| `vcs-api-token` | env_var_name | GITHUB_TOKEN | Specify the environment variable name where the VCS (Version Control System) API token is set. |

### checkout-analysis-target

Check out the source code to be analyzed

| Parameter | Type | Default | Description |
|---|---|---|---|
| `cache-key-prefix` | string | source-v1 |  |
| `is-target-branch-base` | boolean | false | Check-out the BASE branch if true is specified |
| `path` | string |  | Checkout directory (default: job’s working_directory) |

### comment

Add a review comment about the analysis result to the pull request

| Parameter | Type | Default | Description |
|---|---|---|---|
| `analysis-results-path` | string |  | Specify the path to save the analysis results if you need to change it |
| `pattern` | string | .* | Specify pattern to include by regular expression |
| `vcs-api-token` | env_var_name | GITHUB_TOKEN | Specify the environment variable name where the VCS (Version Control System) API token is set. |
| `when` | enum | on_fail | Specify when to enable or disable the step. Takes the following values: always, on_success, on_fail (default: on_fail) |

### declare-commit-ranges

Declare the commit ranges as an environment variable.

This command identifies the BASE commit in the following steps:

1. If there is a pull request associated with the current build, use the VCS API to identify the BASE commit.
2. If the `CIRCLE_COMPARE_URL` environment variable is set, the value identifies the BASE commit.
  - If `CIRCLE_COMPARE_URL.txt` exists even if the `CIRCLE_COMPARE_URL` environment variable is not set,
    the contents of that file will be used as the value of `CIRCLE_COMPARE_URL`.

**Note:**

CircleCI 2.1 will disable the `CIRCLE_COMPARE_URL` environment variable.
Please reconfigure `CIRCLE_COMPARE_URL` somehow.

There are several ways to reconfigure the `CIRCLE_COMPARE_URL` environment variable:

- Use [iynere/compare-url][1] orb
- Use [Pipeline Values][2]

[1]: https://circleci.com/orbs/registry/orb/iynere/compare-url
[2]: https://circleci.com/docs/2.0/pipeline-variables/#pipeline-values


| Parameter | Type | Default | Description |
|---|---|---|---|
| `circle_compare_url-path` | string |  | Specify the path of `CIRCLE_COMPARE_URL.txt` if you are using `iynere/compare-url` orb |
| `vcs-api-token` | env_var_name | GITHUB_TOKEN | Specify the environment variable name where the VCS (Version Control System) API token is set. |

### evaluate

Evaluate analysis results

| Parameter | Type | Default | Description |
|---|---|---|---|
| `analysis-results-path` | string |  | Specify the path to save the analysis results if you need to change it |
| `exit-status-if-detected` | enum | 1 | Specify the exit status if the issue(s) is detected |
| `pattern` | string | .* | Specify pattern to include by regular expression |

### execute-and-evaluate

Calculate the difference of static code analysis results between HEAD branch and BASE branch and then evaluate the result

Note: If parallelism is set to N > 1, the result will not be calculated correctly in most cases.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `analyze` | steps | analyze | Specify analysis steps |
| `circle_compare_url-path` | string |  | Specify the path of `CIRCLE_COMPARE_URL.txt` if you are using `iynere/compare-url` orb |
| `test-results-path` | string | /tmp/test-results | Specify the value of the path parameter in the store_test_results step if you need to change it |
| `vcs-api-token` | env_var_name | GITHUB_TOKEN | Specify the environment variable name where the VCS (Version Control System) API token is set. |

### refine-analysis-result

Refine analysis result

| Parameter | Type | Default | Description |
|---|---|---|---|
| `analysis-results-path` | string |  | Specify the path to save the analysis results if you need to change it (default: /tmp/dscar/analysis-results) |

### restore_comment-fingerprints

Restore comment fingerprints from cache

### save_comment-fingerprints

Save comment fingerprints to cache

| Parameter | Type | Default | Description |
|---|---|---|---|
| `when` | enum | on_fail | Specify when to enable or disable the step. Takes the following values: always, on_success, on_fail (default: on_fail) |

### transform

transform Checkstyle to JUnit

| Parameter | Type | Default | Description |
|---|---|---|---|
| `analysis-results-path` | string |  | Specify the path to save the analysis results if you need to change it (default: /tmp/dscar/analysis-results) |
| `pattern` | string | .* | Specify pattern to include by regular expression |
| `test-results-path` | string | /tmp/test-results | Specify the value of the path parameter in the store_test_results step if you need to change it |
| `when` | enum | on_fail | Specify when to enable or disable the step. Takes the following values: always, on_success, on_fail (default: on_fail) |

## Jobs

### analyze

Analyze the code statically and then evaluate the result

| Parameter | Type | Default | Description |
|---|---|---|---|
| `analyze` | steps | analyze | Specify analysis steps |
| `circle_compare_url-path` | string |  | Specify the path of `CIRCLE_COMPARE_URL.txt` if you are using `iynere/compare-url` orb |
| `executor` | executor | default | Specify the image used to execute analysis |
| `parallelism` | integer | 1 | If parallelism is set to N > 1, then N independent executors will be set up and each will run the steps of that job in parallel. |
| `resource_class` | string | small | Amount of CPU and RAM allocated to each container in a job. |
| `test-results-path` | string | /tmp/test-results | Specify the value of the path parameter in the store_test_results step if you need to change it |
| `vcs-api-token` | env_var_name | GITHUB_TOKEN | Specify the environment variable name where the VCS (Version Control System) API token is set. |

### execute

Calculate the difference of static code analysis results between HEAD branch and BASE branch and then evaluate the result

| Parameter | Type | Default | Description |
|---|---|---|---|
| `analyze` | steps | analyze | Specify analysis steps |
| `circle_compare_url-path` | string |  | Specify the path of `CIRCLE_COMPARE_URL.txt` if you are using `iynere/compare-url` orb |
| `executor` | executor | default | Specify the image used to execute analysis |
| `parallelism` | integer | 1 | If parallelism is set to N > 1, then N independent executors will be set up and each will run the steps of that job in parallel. |
| `resource_class` | string | small | Amount of CPU and RAM allocated to each container in a job. |
| `test-results-path` | string | /tmp/test-results | Specify the value of the path parameter in the store_test_results step if you need to change it |
| `vcs-api-token` | env_var_name | GITHUB_TOKEN | Specify the environment variable name where the VCS (Version Control System) API token is set. |

## Executors

### default

Default analysis execution environment

| Parameter | Type | Default | Description |
|---|---|---|---|
| `analysis-results-path` | string | /tmp/dscar/analysis-results | Specify the path to save the analysis results if you need to change it |
| `docker-image` | string | circleci/node | Specify the image used to execute the analysis |
| `git-base_revision` | string | 0000000000000000000000000000000000000000 | Please set << pipeline.git-base_revision >> |
| `git-revision` | string |  | Please set << pipeline.git-revision >> |
| `project-git_url` | string |  | Please set << pipeline.project.git_url >> |

## Examples

### dscar-reek

Calculate Reek's analysis results for update difference between HEAD branch and BASE branch

```yaml
orbs:
  dscar: moneyforward/dscar@x.y.z
version: 2.1
workflows:
  analyze-code-statically:
    jobs:
      - dscar/execute:
          analyze:
            - dscar/analyze:
                analysis-arguments: '-f xml'
                analysis-command: reek
                analysis-name: Reek
          executor:
            docker-image: circleci/ruby
            git-base_revision: << pipeline.git.base_revision >>
            git-revision: << pipeline.git.revision >>
            name: dscar/default
            project-git_url: << pipeline.project.git_url >>
          name: reek
          pre-steps:
            - run: sudo gem install reek
```