|
1 | 1 | # codacy-cli-v2 |
2 | 2 |
|
3 | | -This is a POC for what could a new CLI for us. The idea is to rely on the native tools and SARIF format instead of relying on docker. |
| 3 | +This is a POC for what could be a new CLI for us. The idea is to rely on the native tools and SARIF format instead of relying on Docker. |
4 | 4 |
|
| 5 | +## Overview |
| 6 | + |
| 7 | +The `codacy-cli-v2` is a command-line tool for Codacy that supports analyzing code using ESLint and uploading the results in SARIF format to Codacy. It provides two main commands: `analyze` and `upload`. |
| 8 | + |
| 9 | +### Commands |
| 10 | + |
| 11 | +- **`analyze` Command**: Runs ESLint analysis on the codebase. |
| 12 | + - `--output, -o`: Output file for the results. |
| 13 | + - `--tool, -t`: Specifies the tool to run analysis with (e.g., ESLint). |
| 14 | + - `--fix, -f`: Automatically fixes issues when possible. |
| 15 | + - `--new-pr`: Creates a new GitHub PR with fixed issues. |
| 16 | + |
| 17 | +- **`upload` Command**: Uploads a SARIF file containing analysis results to Codacy. |
| 18 | + - `--sarif-path, -s`: Path to the SARIF report. |
| 19 | + - `--commit-uuid, -c`: Commit UUID. |
| 20 | + - `--project-token, -t`: Project token for Codacy API. |
| 21 | + |
| 22 | +### Important Concepts |
| 23 | + |
| 24 | +- **`.codacy/.codacy.yaml`**: Configuration file to specify `node` and `eslint` versions for the CLI. |
| 25 | + ```yaml |
| 26 | + runtimes: |
| 27 | + |
| 28 | + tools: |
| 29 | + |
| 30 | + |
| 31 | +- **`codacy-cli-v2 install`**: Command to install the specified node and eslint versions before running analysis. |
| 32 | +- |
5 | 33 | ## Download |
6 | 34 |
|
7 | | -### MacOS brew |
| 35 | +### MacOS (brew) |
| 36 | + |
| 37 | +To install `codacy-cli-v2` using Homebrew: |
8 | 38 |
|
9 | 39 | ```bash |
10 | 40 | brew install codacy/codacy-cli-v2/codacy-cli-v2 |
11 | 41 | ``` |
12 | 42 |
|
13 | | -### Linux |
| 43 | +## Linux |
14 | 44 |
|
15 | | -For linux we rely on `codacy-cli.sh` script on the root, to download the CLI you can: |
| 45 | +For Linux, we rely on the codacy-cli.sh script in the root. To download the CLI, run: |
16 | 46 |
|
17 | 47 | ```bash |
18 | 48 | bash <(curl -Ls https://raw.githubusercontent.com/codacy/codacy-cli-v2/main/codacy-cli.sh) |
19 | 49 | ``` |
| 50 | +You can either put the downloaded script in a specific file or create an alias that will download the script and look for changes: |
20 | 51 |
|
21 | | -You can either put the downloaded script on a specific file, or an alias that will download the script and look for changes: |
22 | 52 | ```bash |
23 | 53 | alias codacy-cli-v2="bash <(curl -Ls https://raw.githubusercontent.com/codacy/codacy-cli-v2/main/codacy-cli.sh)" |
24 | 54 | ``` |
25 | 55 |
|
26 | | -## Important concepts |
27 | | - |
28 | | -### `.codacy/.codacy.yaml` |
29 | | - |
30 | | -Our CLI relies on the `.codacy/.codacy.yaml` to install and run the specified `node` and `eslint` versions. |
| 56 | +## Installation |
31 | 57 |
|
32 | | -Meaning that on the root of the repository that you want to analyse, you should create a `.codacy/.codacy.yaml` such as: |
| 58 | +Before running the analysis, install the specified tools: |
33 | 59 |
|
34 | | -```yaml |
35 | | -runtimes: |
36 | | - |
37 | | -tools: |
38 | | - |
| 60 | +```bash |
| 61 | +codacy-cli-v2 install |
39 | 62 | ``` |
40 | 63 |
|
41 | | -### `codacy-cli-v2 install` |
| 64 | +### Run Analysis |
42 | 65 |
|
43 | | -Before running, you need to do an install command, so it downloads the specified `node` and `eslint` versions. |
44 | | -To install the tools specified on your `.codacy/.codacy.yaml` you should: |
| 66 | +To run ESLint and output the results to the terminal: |
45 | 67 |
|
46 | 68 | ```bash |
47 | | - codacy-cli-v2 install |
| 69 | +codacy-cli-v2 analyze --tool eslint |
48 | 70 | ``` |
49 | 71 |
|
50 | | -## Run |
51 | | - |
52 | | -For now, we only support ESLint, to run and output the results to the terminal: |
| 72 | +To store the results as SARIF in a file: |
53 | 73 |
|
54 | 74 | ```bash |
55 | | -codacy-cli-v2 analyze --tool eslint |
| 75 | +codacy-cli-v2 analyze -t eslint -o eslint.sarif |
56 | 76 | ``` |
57 | 77 |
|
58 | | -Alternatively, you can store the results as SARIF to a file: |
| 78 | +## Upload Results |
| 79 | + |
| 80 | +To upload a SARIF file to Codacy: |
59 | 81 |
|
60 | 82 | ```bash |
61 | | -codacy-cli-v2 analyze -t eslint -o eslint.sarif |
| 83 | +codacy-cli-v2 upload -s path/to/your.sarif -c your-commit-uuid -t your-project-token |
62 | 84 | ``` |
63 | 85 |
|
64 | | -## Example repo |
| 86 | +### Example Repository |
| 87 | + |
| 88 | +As an example, you can check https://github.com/troubleshoot-codacy/eslint-test-examples for a repository that has an action relying on this CLI. |
65 | 89 |
|
66 | | -As an example, that as an action that relies on this CLI, you can check <https://github.com/troubleshoot-codacy/eslint-test-examples> |
|
0 commit comments