From 2e2ac8e601a2be699c888780d592ea567ec1dbdb Mon Sep 17 00:00:00 2001 From: koliveira15 Date: Sat, 23 Mar 2024 22:40:23 -0400 Subject: [PATCH] docs: main readme point to dev site docs: contributing docs: combine explanation docs --- CONTRIBUTING.md | 3 + README.md | 89 +--------- apps/docs-site/astro.config.mjs | 12 +- .../docs/explanation/how-scanning-works.mdx | 54 +++++- .../docs/explanation/sonar-scanner.mdx | 53 ------ .../docs/how-to-guides/contributing.mdx | 165 ++++++++++++++++++ 6 files changed, 231 insertions(+), 145 deletions(-) create mode 100644 CONTRIBUTING.md delete mode 100644 apps/docs-site/src/content/docs/explanation/sonar-scanner.mdx create mode 100644 apps/docs-site/src/content/docs/how-to-guides/contributing.mdx diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..af6ecc1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,3 @@ +# Contributing + +Follow the [contributing how-to guide](https://nx-sonarqube.dev/how-to-guides/contributing) diff --git a/README.md b/README.md index 5f45a30..db93f1b 100644 --- a/README.md +++ b/README.md @@ -1,90 +1,9 @@ # @koliveira15/nx-sonarqube -![logo](https://i.ibb.co/R0bzqtP/nx-sonarqube.png) + -## 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 diff --git a/apps/docs-site/astro.config.mjs b/apps/docs-site/astro.config.mjs index 39e7502..385b837 100644 --- a/apps/docs-site/astro.config.mjs +++ b/apps/docs-site/astro.config.mjs @@ -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' }, + }, ], }), ], diff --git a/apps/docs-site/src/content/docs/explanation/how-scanning-works.mdx b/apps/docs-site/src/content/docs/explanation/how-scanning-works.mdx index 4b593c3..b6c9671 100644 --- a/apps/docs-site/src/content/docs/explanation/how-scanning-works.mdx +++ b/apps/docs-site/src/content/docs/explanation/how-scanning-works.mdx @@ -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). @@ -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 @@ -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. + + diff --git a/apps/docs-site/src/content/docs/explanation/sonar-scanner.mdx b/apps/docs-site/src/content/docs/explanation/sonar-scanner.mdx deleted file mode 100644 index 584d3b4..0000000 --- a/apps/docs-site/src/content/docs/explanation/sonar-scanner.mdx +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Sonar Scanner -sidebar: - order: 2 ---- - -import { Code } from '@astrojs/starlight/components'; -export const projectJson = `{ - "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" - } - } - } - } -}`; - -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. - - diff --git a/apps/docs-site/src/content/docs/how-to-guides/contributing.mdx b/apps/docs-site/src/content/docs/how-to-guides/contributing.mdx new file mode 100644 index 0000000..2ad6f98 --- /dev/null +++ b/apps/docs-site/src/content/docs/how-to-guides/contributing.mdx @@ -0,0 +1,165 @@ +--- +title: Contributing +--- + +nx-sonarqube is an MIT-licensed open source project with its ongoing development made by contributors. + +## Setup Repository + +### Fork + +Follow GitHub's [documentation](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project#cloning-a-fork) +on cloning a fork and creating a branch to work on + +### Dependencies + +nx-sonarqube uses [npm](https://www.npmjs.com/) to manage its dependencies. + +Before opening a pull request, run the following command from the root workspace folder to make sure your development dependencies are up-to-date: + +```shell +npm ci +``` + +## Contributing to the plugin + +### Folder structure + +Source code for the nx-sonarqube plugin exists under the `packages/nx-sonarqube` folder. To contribute features or bug fixes to the framework, locate the relevant code in one of the `packages/nx-sonarqube` sub-folders. + +### Running locally + +Run the following to serve the plugin and link the package to another consuming Nx workspace: + +#### nx-sonarqube Workspace + +Terminal one: + +```shell +npx nx build nx-sonarqube --watch +``` + +Terminal two: + +```shell +cd dist/packages/nx-sonarqube +npm link +``` + +#### Consuming Nx Workspace + +```shell +npm link @koliveira15/nx-sonarqube +``` + +### Commands + +#### Build + +nx-sonarqube uses [Nx](https://nx.dev) for builds. To build the plugin locally, run the following command from the root folder: + +```shell +npx nx build nx-sonarqube +``` + +#### Unit Testing + +nx-sonarqube uses [Jest](https://jestjs.io) for tests. To test the plugin locally, run the following command from the root folder: + +```shell +npx nx test nx-sonarqube +``` + +#### Linting + +nx-sonarqube uses [ESLint](https://eslint.org/) for linting. To lint the plugin locally, run the following command from the root folder: + +```shell +npx nx lint nx-sonarqube +``` + +#### E2E Testing + +To e2e test the plugin locally, run the following command from the root folder: + +```shell +npx nx e2e nx-sonarqube-e2e +``` + +## Contributing to the documentation and nx-sonarqube.dev website + +The documentation site is built using: + +- [Astro](https://docs.astro.build/en/getting-started/) - Web framework for content-drive websites +- [Starlight](https://starlight.astro.build/getting-started/) - Astro plugin for documentation sites +- [Diátaxis](https://diataxis.fr/) - Methodology for documentation authoring + +### Folder structure + +Source code for the nx-sonarqube docs and the nx-sonarqube.dev website exists under the `apps/docs-site` project folder. +To contribute documentation or website content, locate the relevant source code in one of the sub-folders: + +- `src/assets` - Images and other static assets +- `src/content` - Documentation pages with Astro MDX support +- `src/data` - static data file used in examples +- `src/styles` - CSS themes + +### Running locally + +Run the following command from the root of the workspace serve the website: + +```shell +npx nx serve docs-site +``` + +### Commands + +#### Build + +To build the website locally, run the following command from the root folder: + +```shell +npx nx build docs-site +``` + +#### Running static website locally + +To run the generated static website locally, run the following command from the root folder: + +```shell +npx http-server dist/apps/docs-site +``` + +## Submission + +### Pull Requests + +- Rebase your branch against the current `main`. +- Follow the [Setup Repository](#setup-repository) steps above to make sure your forked development environment is up-to-date +- Please ensure the test suite passes before submitting a PR. +- If you've added new functionality, **please** include tests which validate its behavior. +- Make reference to possible [issues](https://github.com/koliveira15/nx-sonarqube/issues) on PR comment. +- PRs may include multiple commits. However, please keep content of all commits related. Raise separate PRs for disjoint changes. + +### Bug Reports + +- Search through [issues](https://github.com/koliveira15/nx-sonarqube/issues) or [PRs](https://github.com/koliveira15/nx-sonarqube/pulls) to see if a previous issue has already been reported and/or fixed. +- Provide a _small_ reproduction using a GitHub repository. +- Use the Bug issue template to open issues + +### New Features + +- We value keeping the API surface small and concise, which factors into whether new features are accepted. +- The feature will be discussed and considered. +- Once the PR is submitted, it will be reviewed and merged once approved. + +## Commit message guidelines + +This repository uses the [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) standards. Your +commit will not pass pre-commit hooks if it's not followed. + +## Questions and requests for support + +Questions and requests for support should not be opened as issues and should be handled in the following ways: + +- Start a new [Q&A Discussion](https://github.com/koliveira15/nx-sonarqube/discussions) on GitHub.