Tidy up parameter naming, add samples (#102)

* Updating parameter names, deprecating old names
* Fix double-logging of tslint exec
* Fixing relative path mapping from tslint output
* Adding a basic sample covering a tslint run and coverage import
* Adding sample on re-using existing tslint output
* Versioning for 1.0.0 RC 1

pom.xml

@@ -5,7 +5,7 @@
   <groupId>com.pablissimo.sonar</groupId>
   <artifactId>sonar-typescript-plugin</artifactId>
   <packaging>sonar-plugin</packaging>
-  <version>0.99.1-SNAPSHOT</version>
+  <version>1.0.0-RC1</version>
 
   <name>TypeScript</name>
   <description>Analyse TypeScript projects</description>

samples/basic-setup/.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+tmp/
+src/*.js
+test/*.js
+*.map
+html/

samples/basic-setup/README.md

@@ -0,0 +1,40 @@
+#Basic setup example
+This sample project can be analysed by SonarQube to demonstrate:
+
+* Linting information from ```tslint```, configured via a ```tslint.json``` file
+* Code coverage metrics from an LCOV file
+
+You can see a live example of the results of analysing this project at [https://sonar.pablissimo.com](https://sonar.pablissimo.com/dashboard?id=com.pablissimo.sonar%3Abasic-setup).
+
+##Building and analysing
+
+* Run ```npm install``` from the cloned repo folder
+* Run ```npm test``` to regenerate code coverage information
+  * You don't *need* to perform this step, a coverage file is already checked into the repository
+
+To analyse with SonarQube just run ```sonar-scanner -X``` from the cloned repo folder.
+
+* The -X flag will give us diagnostic information during the run, so you can see what the plugin is up to
+
+##Breaking down the sonar-project.properties file
+
+The sample has a ```sonar-project.properties``` file that controls how the analysis gets run. We haven't specified anything here that isn't its default or automatically detected - these are explained under the table.
+
+<table>
+<thead><tr><th>Line</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td>sonar.projectKey=com.pablissimo.sonar:basic-setup</td><td>Unique string that identifies this project to SonarQube, differentiating it from any other project that's being analysed by the same server</td></tr>
+<tr><td>sonar.projectName=Basic project setup example</td><td>Name of the project, which will show in the SonarQube admin interface</td></tr>
+<tr><td>sonar.projectVersion=1.0</td><td>Version of the project</td></tr>
+<tr><td>sonar.sources=./src</td><td>The path to the source code for your project - essentially describing the files to be analysed. Specified relative to the sonar-project.properties file.</td></tr>
+<tr><td>sonar.sourceEncoding=UTF-8</td><td>The encoding of your source files - typically UTF-8 is fine, unless you know you're using a different encoding</td></tr>
+<tr><td>sonar.exclusions=node_modules/**</td><td>The files that should be excluded from analysis - here, we don't want to include anything in the node_modules folder as it's full of TypeScript and JavaScript that's got nothing to do with us and would muddy the analysis</td></tr>
+<tr><td>sonar.tests=./test</td><td>The path to any test code you have for your project, which will be excluded when calculating code coverage metrics - but these files are still analysed by the plugin for linting issues</td></tr>
+<tr><td>sonar.ts.coverage.lcovReportPath=coverage/lcov.info</td><td>The path to an LCOV-format file describing code coverage for your project. Typically generated by tools like Karma, Istanbul (with Istanbul-remap), Chutzpah etc</td></tr>
+</tbody>
+</table>
+
+Several settings are automatically detected (and you'll see these listed in the LCOV output):
+
+* The path to ```tslint``` is automatically detected as within the node_modules folder
+* The location to the ```tslint.json``` file that configures tslint is automatically assumed to be the same folder as the ```sonar-project.properties``` file

samples/basic-setup/coverage/lcov.info

@@ -0,0 +1,55 @@
+TN:
+SF:C:\Projects\SonarTsPlugin\samples\basic-setup\src\MyApp.ts
+FN:1,(anonymous_3)
+FN:7,(anonymous_4)
+FN:8,MyStringUtils
+FN:11,(anonymous_6)
+FN:24,(anonymous_7)
+FN:25,(anonymous_9)
+FNF:6
+FNH:5
+FNDA:1,(anonymous_3)
+FNDA:1,(anonymous_4)
+FNDA:1,MyStringUtils
+FNDA:1,(anonymous_6)
+FNDA:1,(anonymous_7)
+FNDA:0,(anonymous_9)
+DA:1,2
+DA:7,1
+DA:8,1
+DA:11,1
+DA:12,1
+DA:13,1
+DA:16,0
+DA:18,1
+DA:24,2
+DA:25,1
+DA:26,0
+DA:29,1
+LF:12
+LH:10
+BRDA:12,1,0,1
+BRDA:12,1,1,0
+BRDA:1,2,0,1
+BRDA:1,2,1,1
+BRF:4
+BRH:3
+end_of_record
+TN:
+SF:C:\Projects\SonarTsPlugin\samples\basic-setup\test\MyAppTests.ts
+FN:3,(anonymous_3)
+FN:4,(anonymous_4)
+FNF:2
+FNH:2
+FNDA:1,(anonymous_3)
+FNDA:1,(anonymous_4)
+DA:1,1
+DA:3,1
+DA:4,1
+DA:5,1
+DA:10,1
+LF:5
+LH:5
+BRF:0
+BRH:0
+end_of_record

samples/basic-setup/karma.conf.js

@@ -0,0 +1,25 @@
+module.exports = function (config) {
+    config.set({
+        frameworks: ["jasmine", "karma-typescript"],
+        files: [
+            { pattern: "src/**/*.ts" },
+            { pattern: "test/**/*.ts" }
+        ],
+        preprocessors: {
+            "**/*.ts": ["karma-typescript"]
+        },
+        reporters: ["progress", "karma-typescript"],
+        browsers: ["PhantomJS"],
+
+        karmaTypescriptConfig: {
+            reports: {
+                "lcovonly": {
+                    directory: "coverage",
+                    subdirectory: ".",
+                    filename: "lcov.info"
+                }
+            },
+            tsconfig: "./tsconfig.json"
+        }
+    });
+};

samples/basic-setup/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "basic-app",
+  "version": "1.0.0",
+
+  "scripts": {
+    "test": "karma start --single-run --code-coverage"
+  },
+
+  "dependencies": {
+    "@types/jasmine": "^2.5.35",
+    "jasmine-core": "^2.5.2",
+    "karma": "^1.4.1",
+    "karma-phantomjs-launcher": "^1.0.2",
+    "karma-cli": "^1.0.1",
+    "karma-jasmine": "^1.1.0",
+    "karma-typescript": "^2.1.7",
+    "typescript": "latest",
+    "tslint": "^4.4.2"
+  },
+
+  "devDependencies": {
+    "gulp": "^3.9.1",
+    "karma-typescript": "^2.1.7"
+  }
+}

samples/basic-setup/sonar-project.properties

@@ -0,0 +1,12 @@
+sonar.projectKey=com.pablissimo.sonar:basic-setup
+sonar.projectName=Basic project setup example
+sonar.projectVersion=1.0
+
+sonar.sources=./src
+sonar.sourceEncoding=UTF-8
+sonar.exclusions=node_modules/**
+
+sonar.tests=./test
+
+# To import the LCOV report
+sonar.ts.coverage.lcovReportPath=coverage/lcov.info

samples/basic-setup/src/MyApp.ts

@@ -0,0 +1,30 @@
+export module MyApp {
+    /*
+        Contains a couple of methods that our test class will call, and
+        some awful code that will cause tslint to flag a couple of basic
+        issues
+    */
+    export class MyStringUtils {
+        constructor(public dummy1: string, public dummy2: string) {
+        }
+
+        public areStringsEqual(s1: string, s2: string) {
+            if (s1 == s2) {
+                return true;
+            }
+            else
+                return false;
+        }
+    }
+
+    /*
+        Contains a method that none of the test code hits, and
+        that tslint will flag another couple of issues on
+    */
+    export class MyUncoveredClass {
+        public justReturn42(param1:string,param2: number) {
+            return 42;
+        }
+
+    }
+}

samples/basic-setup/test/MyAppTests.ts

@@ -0,0 +1,12 @@
+import { MyApp } from "../src/MyApp";
+
+describe("areStringsEqual", () => {
+    it("should return true if two strings are the same", () => {
+        var result =
+            new MyApp
+            .MyStringUtils("whatever", "whoever")
+            .areStringsEqual("t", "t");
+
+        expect(result).toEqual(true);
+    });
+});

samples/basic-setup/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compileOnSave": true,
+  "compilerOptions": {
+    "module": "commonjs",
+    "noImplicitAny": true,
+    "outDir": "tmp",
+    "sourceMap": true,
+    "target": "ES5",
+    "types": [
+      "jasmine"
+    ]
+  },
+  "exclude": [
+    "node_modules"
+  ]
+}

samples/basic-setup/tslint.json

@@ -0,0 +1,102 @@
+{
+    "jsRules": {
+        "class-name": true,
+        "comment-format": [
+            true,
+            "check-space"
+        ],
+        "indent": [
+            true,
+            "spaces"
+        ],
+        "no-duplicate-variable": true,
+        "no-eval": true,
+        "no-trailing-whitespace": true,
+        "no-unsafe-finally": true,
+        "one-line": [
+            true,
+            "check-open-brace",
+            "check-whitespace"
+        ],
+        "quotemark": [
+            true,
+            "double"
+        ],
+        "semicolon": [
+            true,
+            "always"
+        ],
+        "triple-equals": [
+            true,
+            "allow-null-check"
+        ],
+        "variable-name": [
+            true,
+            "ban-keywords"
+        ],
+        "whitespace": [
+            true,
+            "check-branch",
+            "check-decl",
+            "check-operator",
+            "check-separator",
+            "check-type"
+        ]
+    },
+    "rules": {
+        "class-name": true,
+        "comment-format": [
+          true,
+          "check-space"
+        ],
+        "curly": true,
+        "indent": [
+            true,
+            "spaces"
+        ],
+        "no-eval": true,
+        "no-internal-module": true,
+        "no-trailing-whitespace": true,
+        "no-unsafe-finally": true,
+        "no-var-keyword": true,
+        "one-line": [
+            true,
+            "check-open-brace",
+            "check-whitespace"
+        ],
+        "quotemark": [
+            true,
+            "double"
+        ],
+        "semicolon": [
+            true,
+            "always"
+        ],
+        "triple-equals": [
+            true,
+            "allow-null-check"
+        ],
+        "typedef-whitespace": [
+            true,
+            {
+                "call-signature": "nospace",
+                "index-signature": "nospace",
+                "parameter": "nospace",
+                "property-declaration": "nospace",
+                "variable-declaration": "nospace"
+            }
+        ],
+        "variable-name": [
+            true,
+            "ban-keywords"
+        ],
+        "whitespace": [
+            true,
+            "check-branch",
+            "check-decl",
+            "check-operator",
+            "check-separator",
+            "check-type"
+        ]
+    }
+}

samples/using-existing-tslint-output/.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+tmp/
+src/*.js
+test/*.js
+*.map
+html/

samples/using-existing-tslint-output/README.md

@@ -0,0 +1,35 @@
+#Using existing tslint output example
+This sample project can be analysed by SonarQube to demonstrate re-using the output of a build-step ```tslint``` pass, instead of having the plugin perform the analysis itself.
+
+You can see a live example of the results of analysing this project at [https://sonar.pablissimo.com](https://sonar.pablissimo.com/dashboard?id=com.pablissimo.sonar%3Ausing-existing-tslint-output).
+
+This sample is identical to the basic-setup sample but with reuse of tslint output.
+
+##Building and analysing
+
+If you want, you can just analyse this project directly as the tslint output has already been generated. However, to rebuild fully:
+
+* Run ```npm install``` from the cloned repo folder
+* Run ```npm test``` to run unit tests and ```tslint``` analysis, building the ```issues.json``` output file.
+
+To analyse with SonarQube just run ```sonar-scanner -X``` from the cloned repo folder.
+
+* The -X flag will give us diagnostic information during the run, so you can see what the plugin is up to
+
+##Breaking down the sonar-project.properties file
+
+The sample has a ```sonar-project.properties``` file that controls how the analysis gets run. This file differs from the basic-setup example only in one interesting respect:
+
+<table>
+<thead><tr><th>Line</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td>sonar.ts.tslint.outputPath=issues.json</td><td>Tells the plugin to skip running tslint itself, and instead just parse the output of the previous tslint path found in the issues.json file</td></tr>
+</tbody>
+</table>
+
+See the basic-setup example for detail on the other configured settings.
+
+##Retionale
+It's possible that your CI build already performs a ```tslint``` path, since a tslint failure might be considered important enough to break your build (or at least otherwise report on). Since a ```tslint``` path on a large project can take a while, the ```sonar.ts.tslint.outputPath``` setting can be set to reuse the output of the CI call to ```tslint```, reducing the time it takes to perform analysis.
+
+It also allows you to call ```tslint``` with parameters or configuration that the plugin may not easily handle, or otherwise filter or transform the ```tslint``` output before it gets consumed by the plugin.