Skip to content

Commit

Permalink
docs: main readme point to dev site
Browse files Browse the repository at this point in the history 
docs: contributing
docs: combine explanation docs
  • Loading branch information
@koliveira15
koliveira15 committed Mar 26, 2024
1 parent 71ef90d commit 2e2ac8e
Show file tree
Hide file tree
Showing 6 changed files with 231 additions and 145 deletions.
3 changes: 3 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Contributing

Follow the [contributing how-to guide](https://nx-sonarqube.dev/how-to-guides/contributing)
89 changes: 4 additions & 85 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,90 +1,9 @@
# @koliveira15/nx-sonarqube

![logo](https://i.ibb.co/R0bzqtP/nx-sonarqube.png)
<img src='apps/docs-site/src/assets/radar.webp' width='300'>

## About
A Nx Plugin that contains executors and generators to support scanning projects using Sonar

A Nx plugin that scans projects using [SonarQube](https://www.sonarqube.org)
/ [SonarCloud](https://sonarcloud.io).
## Get Started

![graph](https://i.ibb.co/whmZkm2/graph.png)

To analyze project "app", we need to know the its dependencies and sub-dependencies. Using the Nx project graph,
we see that this project has five dependencies, four static and one implicit. With this information,
the plugin gathers the source and coverage paths for the analysis.

Sources:

- apps/app/src
- libs/lib-b/src
- libs/lib-c/src
- libs/libs-d/src
- libs/libs-e/src
- libs/libs-f/src

lcov Paths:

- coverage/apps/app/lcov.info
- coverage/libs/lib-b/lcov.info
- coverage/libs/lib-c/lcov.info
- coverage/libs/libs-d/lcov.info
- coverage/libs/libs-e/lcov.info
- coverage/libs/libs-f/lcov.info

## Usage

### Prerequisites

1. Nx workspace
2. SonarQube or Sonar Cloud instance
3. Jest/Vite tests & code coverage enabled

### Installation

1. Install the package:
```bash
npm i -D @koliveira15/nx-sonarqube
```
2. Execute the configuration generator to setup sonar for a given project:
```bash
npx nx g @koliveira15/nx-sonarqube:config
```
3. Execute the sonar target for the given project:
```bash
npx nx sonar my-project
```
or
```bash
npx nx affected --target sonar --parallel 1
```
**Note:** Due to limitations with the scanner, you cannot run more than one scan in parallel

## Authentication

Sonar can require authentication credentials. You can set these via environment variables using [Nrwl's Nx recipe](https://nx.dev/recipes/environment-variables/define-environment-variables)

**SONAR_LOGIN:** The authentication token or login of a SonarQube user with either Execute Analysis permission on the project or Global Execute Analysis permission

**SONAR_PASSWORD:** If you're using an authentication token, leave this blank. If you're using a login, this is the password that goes with your SONAR_LOGIN username

## Customization

Modify the executor options based on the configuration table below. These options are based on [Analysis Parameters](https://docs.sonarqube.org/latest/analysis/analysis-parameters/)

| Name | Required | Description | Default |
| ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| hostUrl | Yes | Sonar server URL | http://localhost:9000 |
| projectKey | Yes | The project's unique key. Allowed characters are: letters, numbers, -, \_, . and :, with at least one non-digit. | |
| branch | No | The branch name | |
| exclusions | No | Files to exclude from coverage | |
| organization | No | Sonar organization | |
| projectName | No | Name of the project that will be displayed on the web interface | |
| projectVersion | No | The project version. | this will default to the package.json version of the app/lib, otherwise it will take the root version |
| qualityGate | No | Forces the analysis step to poll the SonarQube instance and wait for the Quality Gate status | true |
| qualityGateTimeout | No | Sets the number of seconds that the scanner should wait for a report to be processed | 300 |
| skipImplicitDeps | No | Skips adding implicit dependencies to the project graph analysis | false |
| testInclusions | No | Comma-delimited list of test file path patterns to be included in analysis. When set, only test files matching the paths set here will be included in analysis | \*_/_.spec.ts |
| verbose | No | Add more detail to both client and server-side analysis logs | false |
| extra | No | A key value pair for any extra sonar variable that is not included in the list above | |

In Addition, the plugin recognizes any environment variable that is prefixed by `SONAR` and will add it to the sonar executor variables. For example the environment variable `SONAR_LOG_LEVEL=DEBUG` will be recognized as `sonar.log.level=DEBUG`
Go to the [documentation site](https://nx-sonarqube.dev/) to get started
12 changes: 8 additions & 4 deletions apps/docs-site/astro.config.mjs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,18 +42,22 @@ export default defineConfig({
},
],
},
{
label: 'Tutorials',
autogenerate: { directory: 'tutorials' },
},
{
label: 'Explanation',
autogenerate: { directory: 'explanation' },
},
{
label: 'How-To Guides',
autogenerate: { directory: 'how-to-guides' },
},
{
label: 'Reference',
autogenerate: { directory: 'reference' },
},
{
label: 'Tutorials',
autogenerate: { directory: 'tutorials' },
},
],
}),
],
Expand Down
54 changes: 51 additions & 3 deletions apps/docs-site/src/content/docs/explanation/how-scanning-works.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,31 @@ import { Tabs, TabItem } from '@astrojs/starlight/components';
import jestConfig from '../../../data/examples/jest.config?raw';
import viteConfig from '../../../data/examples/vite.config.tmpl?raw';
import projectJson from '../../../data/examples/executor.json?raw';
export const extraProjectJson = `{
"name": "app",
"$schema": "../../node_modules/nx/schemas/project-schema.json",
"projectType": "application",
"sourceRoot": "apps/app/src",
"targets": {
"sonar": {
"executor": "@koliveira15/nx-sonarqube:scan",
"options": {
"hostUrl": "https://sonarcloud.io",
"projectKey": "app",
"extra": {
"sonar.log.level": "DEBUG"
}
}
}
}
}`;

Sonar is a powerful tool for code quality analysis, offering insights into code health, bugs, vulnerabilities, and more.
This document explains how scanning works with nx-sonarqube and Sonar.

## Dependency Graph
## What is Included?

### Dependency Graph

Working in a monorepo typically involves an application project and imported library projects. One of Nx's most
important features is to calculate how projects depend on each other called the [dependency graph](https://nx.dev/nx-api/nx/documents/dep-graph#graph).
Expand All @@ -35,8 +55,6 @@ The project `app` has the following dependencies that will be included in the sc
- 1 dynamic (`lib-d`)
- 1 implicit (`lib-e`)

## What is Included?

Based on the dependency graph above, the following is added to the Sonar analysis:

```shell
Expand Down Expand Up @@ -98,3 +116,33 @@ or [Vitest](https://nx.dev/nx-api/vite/executors/test) configurations:
:::caution
Coverage paths should not be overridden as this is core feature of the plugin which uses the dependency graph
:::

## Scanner Scanner

The Nx plugin wraps the [sonarqube-scanner](https://github.com/SonarSource/sonar-scanner-npm) npm package.
Options for the scanner are passed in via the [executor properties](/reference/executors/scan/#options) into the
[`getScannerOptions()`](https://github.com/koliveira15/nx-sonarqube/blob/main/packages/nx-sonarqube/src/executors/scan/utils/utils.ts) method of the plugin.

The following sections are explain how to pass other options into the scanner outside the executor options:

### Sonar Environment Variables

You can pass extra options to the scanner by using environment variables like so:

```shell
SONAR_LOG_LEVEL=DEBUG npx nx sonar my-app
```

Will be combined into the period-delimited string as `sonar.log.level=DEBUG`

### Extra Property

The scan executor offers an [extra](/reference/executors/scan/#extra) property in which other sonar scanner options
can be passed into the scanner that the scan executor doesn't officially support.

<Code
code={extraProjectJson}
lang="json"
title="apps/app/project.json"
mark="extra"
/>
53 changes: 0 additions & 53 deletions apps/docs-site/src/content/docs/explanation/sonar-scanner.mdx
View file

This file was deleted.

Loading

0 comments on commit 2e2ac8e

Please sign in to comment.