From bf30f8c252c1b9af9ba2d97759bc9cec4c4d5690 Mon Sep 17 00:00:00 2001 From: Alejandro Rizzo Date: Mon, 26 May 2025 14:47:12 +0100 Subject: [PATCH 1/4] clean: updated README --- README.md | 209 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 155 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index 4d3ca532..753d0845 100644 --- a/README.md +++ b/README.md @@ -1,117 +1,218 @@ -# codacy-cli-v2 +# Codacy CLI v2 -The Codacy CLI (version 2) is a command-line tool that supports analyzing code using tools like ESLint and uploading the results in SARIF format to Codacy. -The tool is invoked using the `codacy-cli` command, and provides two main commands: analyze and upload. +Codacy CLI (version 2) is a command-line tool for running code analysis and integrating with Codacy. If your repository exists in Codacy, you can sync your configuration to ensure consistency with your organization's standards. -### Commands +You can also use Codacy CLI for local code analysis without a Codacy account, leveraging the linter configuration files found in your project's root. -- **`analyze` Command**: Runs ESLint analysis on the codebase. - - `--output, -o`: Output file for the results. - - `--tool, -t`: Specifies the tool to run analysis with (e.g., ESLint). - - `--format`: Output format (use 'sarif' for SARIF format to terminal). - - `--fix`: Automatically fixes issues when possible. +The CLI supports uploading analysis results (in [SARIF](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) format) to Codacy as well. -- **`upload` Command With Project Token**: Uploads a SARIF file containing analysis results to Codacy. - - `--sarif-path, -s`: Path to the SARIF report. - - `--commit-uuid, -c`: Commit UUID. - - `--project-token, -t`: Project token for Codacy API. +It is invoked using the `codacy-cli` command and provides several commands for project setup, analysis, and integration. -- **`upload` Command With API Token**: Uploads a SARIF file containing analysis results to Codacy. - - `--sarif-path, -s`: Path to the SARIF report. - - `--commit-uuid, -c`: Commit UUID. - - `--api-token, -a`: User level token for Codacy API. - - `--provider, -p`: Provider name (e.g., gh, gl, bb). - - `--owner, -o`: Repository owner. - - `--repository, -r`: Repository name. +--- -### Important Concepts +## Supported Platforms -- **`.codacy/codacy.yaml`**: Configuration file to specify runtimes and tools versions for the CLI. - ```yaml - runtimes: - - node@22.2.0 - tools: - - eslint@8.57.0 - -- **`codacy-cli install`**: Command to install the specified node and eslint versions before running analysis. +- **macOS** +- **Linux** +- **Windows (via WSL only)** -## Download +> **Note:** Native Windows is not yet supported. For Windows, use [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/) and follow the Linux instructions inside your WSL terminal. -### MacOS (brew) +--- -To install `codacy-cli` using Homebrew: +## Installation + +### macOS (Homebrew) ```bash brew install codacy/codacy-cli-v2/codacy-cli-v2 ``` -### Linux +### Linux / Windows (WSL) -For Linux, we rely on the codacy-cli.sh script in the root. To download the CLI, run: +Run the following in your terminal (Linux or WSL): ```bash bash <(curl -Ls https://raw.githubusercontent.com/codacy/codacy-cli-v2/main/codacy-cli.sh) ``` -You can either put the downloaded script in a specific file or create an alias that will download the script and look for changes: + +Or create an alias for convenience: ```bash alias codacy-cli="bash <(curl -Ls https://raw.githubusercontent.com/codacy/codacy-cli-v2/main/codacy-cli.sh)" ``` -## Installation +--- + +## CLI Commands + +### `init` — Bootstrap Project Configuration -Before running the analysis, install the specified tools: +Bootstraps the CLI configuration in your project's folder. This command creates a `.codacy` directory containing a `codacy.yaml` file, which specifies the runtimes and tools that will be used and installed. + +- If you provide Codacy repository information (API token, provider, organization, repository), the configuration will be fetched from Codacy, ensuring consistency with your organization's standards. +- If no Codacy information is provided, all available tools will be included. For each tool, if a local configuration file exists in your project, it will be used; otherwise, an empty configuration file will be created for that tool. + +- **Local mode (local configuration files):** + ```bash + codacy-cli init + ``` +- **Remote mode (fetch configuration from Codacy):** + ```bash + codacy-cli init --api-token --provider --organization --repository + ``` + +**Flags:** +- `--api-token` (string): Codacy API token (optional; enables fetching remote config) +- `--provider` (string): Provider (`gh`, `gl`, `bb`), required with `--api-token` +- `--organization` (string): Organization name, required with `--api-token` +- `--repository` (string): Repository name, required with `--api-token` + +### `install` — Install Runtimes and Tools + +Installs all runtimes and tools specified in `.codacy/codacy.yaml`: +- Downloads and extracts runtimes (Node, Python, Dart, Java, etc.) +- Installs tools (ESLint, Trivy, Pylint, PMD, etc.) using the correct package manager or direct download +- Handles platform-specific details +- Skips already installed components (e.g., Node, Python, Dart, Java, etc.) +- Shows a progress bar and reports any failures ```bash codacy-cli install ``` +- Optionally specify a custom registry: + ```bash + codacy-cli install --registry + ``` -## Run Analysis +### `analyze` — Run Code Analysis -To run ESLint and output the results to the terminal: +Runs all configured tools, or a specific tool, on your codebase. ```bash +# Run all tools +tcodacy-cli analyze + +# Run a specific tool (e.g., ESLint) codacy-cli analyze --tool eslint + +# Output results in SARIF format +tcodacy-cli analyze --tool eslint --format sarif + +# Store results as SARIF in a file +codacy-cli analyze -t eslint --format sarif -o eslint.sarif + +# Analyze a specific file with all configured tools +codacy-cli analyze path/to/file.js + +# Analyze a specific file with a specific tool (e.g., ESLint) +codacy-cli analyze --tool eslint path/to/file.js ``` -To output results in SARIF format to the terminal: +**Flags:** +- `--output, -o`: Output file for the results; if not provided, results will be printed to the console +- `--tool, -t`: Tool to run analysis with (e.g., eslint) +- `--format`: Output format (e.g., `sarif`) +- `--fix`: Automatically fix issues when possible + +### `upload` — Upload SARIF Results to Codacy + +Uploads a SARIF file containing analysis results to Codacy. ```bash -codacy-cli analyze --tool eslint --format sarif +# With project token +codacy-cli upload -s path/to/your.sarif -c -t + +# With API token +codacy-cli upload -s path/to/your.sarif -c -a -p -o -r ``` -To store the results as SARIF in a file: +**Flags:** +- `--sarif-path, -s`: Path to the SARIF report (required) +- `--commit-uuid, -c`: Commit UUID +- `--project-token, -t`: Project token for Codacy API +- `--api-token, -a`: User-level token for Codacy API +- `--provider, -p`: Provider name (e.g., gh, gl, bb) +- `--owner, -o`: Repository owner +- `--repository, -r`: Repository name + +### `update` — Update the CLI + +Fetches and installs the latest version of the CLI. ```bash -codacy-cli analyze -t eslint --format sarif -o eslint.sarif +codacy-cli update ``` -## Upload Results +### `version` — Show Version Information -To upload a SARIF file to Codacy: +Displays detailed version/build information for the CLI. ```bash -codacy-cli upload -s path/to/your.sarif -c your-commit-uuid -t your-project-token +codacy-cli version ``` -## Breaking Changes +--- + +## Configuration -Some behaviors have changed with the new updates of the CLI. To rely on a specific version, you can add that version to your environment: +- **`.codacy/codacy.yaml`**: Main configuration file specifying runtimes and tool versions. +- **`.codacy/tools-configs/`**: Tool-specific configuration files (auto-generated or fetched from Codacy). +--- + +## Example Usage + +```bash +# 1. Initialize project (local or remote) +codacy-cli init +# or +codacy-cli init --api-token --provider gh --organization my-org --repository my-repo + +# 2. Install all required runtimes and tools +codacy-cli install + +# 3. Run analysis (all tools or specific tool) +codacy-cli analyze +codacy-cli analyze --tool eslint + +# 4. Upload results to Codacy +codacy-cli upload -s eslint.sarif -c -t ``` -export CODACY_CLI_V2_VERSION="1.0.0-main.133.3607792" + +--- + +## Troubleshooting + +### WSL (Windows Subsystem for Linux) +- **Always use a WSL terminal** (e.g., Ubuntu on Windows) for all commands. +- Ensure you have the latest version of WSL and a supported Linux distribution installed. +- If you see errors related to missing Linux tools (e.g., `curl`, `tar`), install them using your WSL package manager (e.g., `sudo apt install curl tar`). + +### MacOS: Errors related to `docker-credential-osxkeychain` not found + +Install the docker credential helper: + +```bash +brew install docker-credential-helper ``` +--- + ## Example Repository -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. +See [eslint-test-examples](https://github.com/troubleshoot-codacy/eslint-test-examples) for a repository using this CLI in GitHub Actions. -## Troubleshooting +--- -#### Errors related to `docker-credential-osxkeychain` not found when running analysis +## Breaking Changes & Version Pinning -Install the docker credential helper. For example, in MacOS: +Some behaviors have changed with recent updates. To rely on a specific CLI version, set the following environment variable: ```bash -brew install docker-credential-helper +export CODACY_CLI_V2_VERSION="1.0.0-main.133.3607792" ``` + +Check the [releases](https://github.com/codacy/codacy-cli-v2/releases) page for all available versions. + +--- From 62a000908e6a88c54ea83af1b7c5dd95d8d5f60f Mon Sep 17 00:00:00 2001 From: Alejandro Rizzo Date: Mon, 26 May 2025 14:50:40 +0100 Subject: [PATCH 2/4] add codacy badges --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 753d0845..f8803153 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,8 @@ # Codacy CLI v2 +[![Codacy Badge](https://app.codacy.com/project/badge/Grade/8cae070168cf488db82478ba6505a005)](https://app.codacy.com/gh/codacy/codacy-cli-v2/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) [![Codacy Badge](https://app.codacy.com/project/badge/Coverage/8cae070168cf488db82478ba6505a005)](https://app.codacy.com/gh/codacy/codacy-cli-v2/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage) + + Codacy CLI (version 2) is a command-line tool for running code analysis and integrating with Codacy. If your repository exists in Codacy, you can sync your configuration to ensure consistency with your organization's standards. You can also use Codacy CLI for local code analysis without a Codacy account, leveraging the linter configuration files found in your project's root. From b126263daf24fed317b348480ba51d7c87a2438e Mon Sep 17 00:00:00 2001 From: Alejandro Rizzo Date: Mon, 26 May 2025 15:14:49 +0100 Subject: [PATCH 3/4] Update README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f8803153..b9da27ff 100644 --- a/README.md +++ b/README.md @@ -94,13 +94,13 @@ Runs all configured tools, or a specific tool, on your codebase. ```bash # Run all tools -tcodacy-cli analyze +codacy-cli analyze # Run a specific tool (e.g., ESLint) codacy-cli analyze --tool eslint # Output results in SARIF format -tcodacy-cli analyze --tool eslint --format sarif +codacy-cli analyze --tool eslint --format sarif # Store results as SARIF in a file codacy-cli analyze -t eslint --format sarif -o eslint.sarif From 036aaf43f92a1626d7852e0960e0da1264371150 Mon Sep 17 00:00:00 2001 From: Alejandro Rizzo Date: Tue, 27 May 2025 09:32:34 +0100 Subject: [PATCH 4/4] PR review comments --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b9da27ff..0996acf6 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ Codacy CLI (version 2) is a command-line tool for running code analysis and integrating with Codacy. If your repository exists in Codacy, you can sync your configuration to ensure consistency with your organization's standards. -You can also use Codacy CLI for local code analysis without a Codacy account, leveraging the linter configuration files found in your project's root. +You can also use Codacy CLI for local code analysis without a Codacy account, leveraging the linter configuration files found in your project's root or Codacy's suggested defaults. The CLI supports uploading analysis results (in [SARIF](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) format) to Codacy as well. @@ -54,7 +54,7 @@ alias codacy-cli="bash <(curl -Ls https://raw.githubusercontent.com/codacy/codac Bootstraps the CLI configuration in your project's folder. This command creates a `.codacy` directory containing a `codacy.yaml` file, which specifies the runtimes and tools that will be used and installed. - If you provide Codacy repository information (API token, provider, organization, repository), the configuration will be fetched from Codacy, ensuring consistency with your organization's standards. -- If no Codacy information is provided, all available tools will be included. For each tool, if a local configuration file exists in your project, it will be used; otherwise, an empty configuration file will be created for that tool. +- If no Codacy information is provided, all available tools will be included. For each tool, if a local configuration file exists in your project, it will be used; otherwise, Codacy's suggested defaults will be used. - **Local mode (local configuration files):** ```bash