SonarQube plugin for TypeScript files
A live deployed demo hitting a few varied TypeScript projects can be found here: https://sonar.pablissimo.com.
The plugin is tested against different permutations of the SonarQube server and scanner using the sample projects listed below. The test servers are as follows:
Some sample projects are provided to demonstrate different configuration options in the samples/ folder.
- basic-setup - a standard
tslintpass with code coverage - using-existing-tslint-output - as above, but re-using the output of a build-step
tslintpass rather than the plugin running it itself
This is plugin for SonarQube 5.6+ for analysing projects with TypeScript content that supports:
- TsLint for code quality information
- Importing LCOV files for unit test coverage information
- NCLOC metric generation
- Java 1.8+
- SonarQube 5.6 LTS+
- TsLint 2.4.0+
- Download the source
- Build with maven, mvn clean && mvn install
- Install Node.js
- Install TsLint (2.4.0+) with
npm install -g tslint, or ensure it is installed locally against your project- If you're installing globally, find the path to TsLint and copy it - will be similar to
C:\Users\[Username]\AppData\Roaming\npm\node_modules\tslint\bin\tslinton Windows
- If you're installing globally, find the path to TsLint and copy it - will be similar to
- Copy .jar file (from
target/after build, or downloaded from Releases page) to SonarQube extensions/plugins folder - Restart SonarQube server
- Browse to SonarQube web interface, login as Admin, hit up Settings
- Find the TypeScript tab, paste in the TsLint path
- Hit the Rules tab, then the TsLint rule set, then apply it to your project - alter rule activation as required
- Make sure you have a
tslint.jsonfile next tosonar-project.properties, or specify its path using thesonar.ts.tslint.configPathsetting - If LCOV data available, add sonar.ts.coverage.lcovReportPath=lcov.dat to your sonar-project.properties file (replace lcov.dat with your lcov output, will be sought relative to the sonar-project.properties file)
- Run
sonar-runnerorsonar-scanner - TsLint rule breaches should be shown in the web view
This is an example of what a project configuration file (sonar-project.properties) could look like:
sonar.projectKey=company:my-application
sonar.projectName=My Application
sonar.projectVersion=1.0
sonar.sourceEncoding=UTF-8
sonar.sources=src/app
sonar.exclusions=**/node_modules/**,**/*.spec.ts
sonar.tests=src/app
sonar.test.inclusions=**/*.spec.ts
sonar.ts.tslint.configPath=tslint.json
sonar.ts.coverage.lcovReportPath=test-results/coverage/coverage.lcov
- See the Analysis Parameters documentation page for general configuration options.
- See the Narrowing the Focus documentation page for configuration options related to which files to include.
- See the rest of this README for the SonarTsPlugin specific configuration options.
| Key | Description | |
|---|---|---|
| sonar.ts.tslint.ruleConfigs | Optional | A list of configurations to map custom TsLint rules to dedicated SonarQube rules & settings - see TsLint Custom Rules section below |
| Key | Description | |
|---|---|---|
| sonar.ts.tslint.path | Optional | Path to the installed copy of `tslint` to use - will be automatically sought in node_modules next to the sonar-project.properties file if not specified |
| sonar.ts.tslint.configPath | Optional | Path to the tslint.json file that configures the rules to be used in linting - will be automatically sought in the same folder as the sonar-project.properties file if not specified |
| sonar.ts.tslint.outputPath | Optional | If your existing CI process already runs `tslint` you can have the plugin re-use its output using the `outputPath` setting. The output is expected to be in JSON form |
| sonar.ts.excludeTypeDefinitionFiles | Optional | Excludes .d.ts files from analysis, defaults to true |
| sonar.ts.coverage.forceZeroIfUnspecified | Optional | Forces code coverage percentage to zero for all files when no LCOV report is supplied, defaults to false |
| sonar.ts.coverage.ignoreNotFound | Optional | Controls if a single file should be reported as 0% covered if it doesn't appear in the LCOV report, defaults to false |
| sonar.ts.tslint.timeout | Optional | Max time to wait for `tslint` to finish processing a single file (in milliseconds), defaults to 60 seconds |
| sonar.ts.tslint.rulesDir | Optional | Path to a folder containing custom `tslint` rules referenced in tslint.json, if any is required |
| sonar.ts.coverage.lcovReportPath | Optional | Path to an LCOV code-coverage report to be used to calculate coverage metrics for your project |
| sonar.ts.tslint.nodePath | Optional | Path to custom node to execute |
| sonar.ts.tslint.projectPath | Optional | Path to tsconfig.json that describes the TypeScript files in your project to analyse, rather than letting SonarQube search for them automatically. Required to allow sonar.ts.tslint.typeCheck to work. |
| sonar.ts.tslint.typeCheck | Optional | If true, asks tslint to run type-checking, allowing tslint rules that need type information to operate. Requires that you have specified sonar.ts.tslint.projectPath. |
By default, SonarTsPlugin will look for a version of TsLint installed locally within your project (i.e. in node_modules\tslint\bin), relative to the sonar-project.properties file. This may not be what you want, so you can set this directly via the sonar.ts.tslint.path configuration setting:
- At project level
- Globally, for all projects
If analysis is failing, run sonar-scanner with the -X option for more diagnostic information, including a note of where the plugin is searching for tslint. Bear in mind that if running on a build server, the account running the build will need access to the path to tslint.
By default, SonarTsPlugin will look for a tslint configuration file called tslint.json next to the sonar-project.properties file. You can override this using the sonar.ts.tslint.configPath configuration setting if this isn't the case for your project.
To present custom tslint rules in SonarQube analysis, you can provide a configuration that maps the rules from your sonar.ts.tslint.rulesDir directory to dedicated Sonar rules for analysis.
The configuration for a tslint Sonar rule consists of a line declaring the TSLint rule id, a boolean switch to enable or disable the rule if needed and some attached properties that are used by Sonar for analysis and reporting.
For example, let's take the export-name rule from the tslint-microsoft-contrib package. A configuration for that rule in SonarTsPlugin could look as follows:
export-name=true
export-name.name=The name of the exported module must match the filename of the source file.
export-name.severity=MAJOR
export-name.description=This is case-sensitive but ignores file extension. Since version 1.0, this rule takes a list of regular expressions as a parameter. Any export name matching that regular expression will be ignored.
export-name.debtFunc=LINEAR_OFFSET
export-name.debtScalar=15min
export-name.debtOffset=1h
export-name.debtType=HARDWARE_RELATED_PORTABILITY
You will need to restart the SonarQube server after configuring custom rules this way before subsequent analyses will pick them up. You will also need to activate the new rules after restart for any quality profile you want them to participate in - by default they will be disabled.
- For documentation about the
technical debtparameters look here and here - For possible values for
debtTypego here
MIT
Thanks to the following for contributions to the plugin:
- Alex Krauss and Manuel Huber for work on improving compatibility with *nix OSes
- schnee3 for giving us some NCLOC support
- drywolf for TSX file and better custom rule mapping
- NikitaEgorov for changes to support consuming existing tslint output
- The LCOV parser is directly copied from the community JavaScript SonarQube plug-in, which is LGPL'd.