How Scanning Works

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.

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. The dependency graph is core to how the nx-sonarqube Nx Plugin can determine which projects to include in a given scan.

There are three kinds of dependencies the graph can calculate:

• Static - a hardcoded import
• Dynamic - a runtime import (e.g. lazy-loaded routes)
• Implicit - not associated with any file or code

Here is an example of the dependency graph for a project app to be scanned:

The project app has the following dependencies that will be included in the scan:

• 4 static (app, lib-a, lib-b, lib-c)
• 1 dynamic (lib-d)
• 1 implicit (lib-e)

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

Included sources paths: apps/app/src,libs/lib-a/src,libs/lib-b/src,libs/lib-c/src,libs/lib-d/src,libs/lib-e/src
Included lcov paths: coverage/apps/app,coverage/libs/lib-a,coverage/libs/lib-b,coverage/libs/lib-c,coverage/libs/lib-d,coverage/libs/lib-e

Source Code

The source code is the code which, presumably, is included in your production build output. This is the code that developers would like scanned to find bugs, code smells, etc.

The source code paths are included in the scanner by using the respective project.json’s sourceRoot property:

apps/app/project.json

{
  "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"
      }
    }
  }
}

Caution

Source code paths should not be overridden as this is core feature of the plugin which uses the dependency graph

Caution

The scanner will default to using project root (e.g., apps/app) if sourceRoot is not present since it can be an optional project configuration property

Unit Test Coverage

Unit test coverage refers to a metric used in software development to measure the extent to which the source code of a program is executed when its unit tests run. It quantifies the amount of source code that is tested by unit tests.

The unit test coverage report (lcov) is determined based on the supported Jest or Vitest configurations:

Jest

libs/lib-a/jest.config.ts

export default {
  displayName: 'lib-a',
  preset: '../../jest.preset.js',
  setupFilesAfterEnv: ['<rootDir>/src/test-setup.ts'],
  coverageDirectory: '../../coverage/libs/lib-a',
  transform: {
    '^.+\\.(ts|mjs|js|html)$': [
      'jest-preset-angular',
      {
        tsconfig: '<rootDir>/tsconfig.spec.json',
        stringifyContentPathRegex: '\\.(html|svg)$',
      },
    ],
  },
  transformIgnorePatterns: ['node_modules/(?!.*\\.mjs$)'],
  snapshotSerializers: [
    'jest-preset-angular/build/serializers/no-ng-attributes',
    'jest-preset-angular/build/serializers/ng-snapshot',
    'jest-preset-angular/build/serializers/html-comment',
  ],
};

Vitest

libs/lib-e/vitest.config.ts

import { defineConfig } from 'vite';

export default defineConfig({
  root: __dirname,
  cacheDir: '../../node_modules/.vite/libs/lib-e',
  test: {
    globals: true,
    cache: { dir: '../../node_modules/.vitest' },
    environment: 'node',
    include: ['src/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
    reporters: ['default'],
    coverage: { reportsDirectory: '../../coverage/libs/lib-e', provider: 'v8' },
  },
});

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 npm package. Options for the scanner are passed in via the executor properties into the getScannerOptions() 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:

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 property in which other sonar scanner options can be passed into the scanner that the scan executor doesn’t officially support.

apps/app/project.json

{
  "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"
        }
      }
    }
  }
}