Updates to deps, adding docs, adding optional typescript compiler ove…

…rride. (#2)

* Updating package.json dependencies, bumping to 0.5.0

* Adding ability to override typescript.

* Updating documentation.

* Minor updates to readme.

* Adding example project links, related projects section, license section.

* Making the error logging a bit more resilient.

README.md

@@ -1,3 +1,92 @@
-# gulp-core-build-typescript [![npm version](https://badge.fury.io/js/%40microsoft%2Fgulp-core-build-typescript.svg)](https://badge.fury.io/js/%40microsoft%2Fgulp-core-build-typescript)
+@microsoft/gulp-core-build-typescript
+=====================================
+A set of gulp-core-build tasks for building TypeScript code.
 
-[![Build Status](https://travis-ci.org/Microsoft/gulp-core-build-typescript.svg?branch=master)](https://travis-ci.org/Microsoft/gulp-core-build-typescript) [![Dependencies](https://david-dm.org/Microsoft/gulp-core-build-typescript.svg)](https://david-dm.org/Microsoft/gulp-core-build-typescript)
+[![npm version](https://badge.fury.io/js/%40microsoft%2Fgulp-core-build-typescript.svg)](https://badge.fury.io/js/%40microsoft%2Fgulp-core-build-typescript)
+[![Build Status](https://travis-ci.org/Microsoft/gulp-core-build-typescript.svg?branch=master)](https://travis-ci.org/Microsoft/gulp-core-build-typescript)
+[![Dependencies](https://david-dm.org/Microsoft/gulp-core-build-typescript.svg)](https://david-dm.org/Microsoft/gulp-core-build-typescript)
+
+# Usage
+
+This collection of tasks is designed to be used with a gulp-core-build based build setup. It abstracts the TypeScript based build tasks used to build typescript code.
+
+The tasks exported are:
+
+* `typescript` - The task for building TypeScript into JavaScript.
+* `tslint` - The task for linting the TypeScript code.
+* `text` - Converts text files into JavaScript.
+
+To use these tasks in your build setup, simply import the package and add the task to a build task group.
+
+```typescript
+import { task, serial, parallel, watch, CopyTask, IExecutable } from '@microsoft/gulp-core-build';
+import { typescript, tslint, text } from '@microsoft/gulp-core-build-typescript';
+
+export * from '@microsoft/gulp-core-build';
+export * from '@microsoft/gulp-core-build-typescript';
+
+// Examples of creating some copy tasks to be run pre/post build.
+export const preCopy: CopyTask = new CopyTask();
+preCopy.name = 'pre-copy';
+
+export const postCopy: CopyTask = new CopyTask();
+postCopy.name = 'post-copy';
+
+// Define a task group.
+task('build', serial(preCopy, parallel(tslint, typescript, text), postCopy));
+```
+
+Some examples of build packages that use this task:
+
+* [@microsoft/web-library-build](https://github.com/Microsoft/web-library-build)
+* [@microsoft/node-library-build](https://github.com/Microsoft/node-library-build)
+
+# Configuring task options
+
+Use the standard "setConfig" method on task instances to set their configuration options. Example:
+
+```typescript
+import { typescript } from '@microsoft/gulp-core-build-typescript';
+
+typescript.setConfig({
+  typescript: require('typescript')
+});
+```
+
+## `typescript` task options
+
+See the `ITypeScriptTaskConfig` interface for the definition.
+
+* `failBuildOnErrors` (boolean, default: true) - Fails the build when errors occur.
+* `sourceMatch` (string[]) - Glob matches for files to be included in the build.
+* `staticMatch` (string[]) - Files that should by passed through (copied) to the build output.
+* `reporter` - Custom TypeScript reporter.
+* `typescript` - Optional override of the typescript compiler. Set this to the result of require('typescript').
+
+## `tslint` task options
+
+See the `ITSLintTaskConfig` interface for the definition.
+
+* `lintConfig` (Object) - The tslint configuration object.
+* `rulesDirectory` (string | string[]) - Directories to search for custom linter rules
+* `sourceMatch` (string[]) - Provides the glob matches for files to be analyzed.
+* `reporter` ((result: lintTypes.LintResult, file: gutil.File, options: ITSLintTaskConfig) => void;) - A function which reports errors to the proper location. Defaults to using the base GulpTask's this.fileError() function.
+* `displayAsWarning` (boolean, default: false) - If true, displays warnings as errors. If the reporter function is overwritten, it should reference
+* `remoteExistingRules` (boolean, default: false) - If true, the lintConfig rules which were previously set will be removed. This flag is useful for ensuring that there are no rules activated from previous calls to setConfig().
+* `useDefaultConfigAsBase` (boolean, default: true) - If false, does not use a default tslint configuration as the basis for creating the list of active rules.
+
+## `text` task options
+
+See the `ITextTaskConfig` interface for the definition.
+
+* `textMatch` (string[]) - Glob matches for files that should be converted into modules.
+
+# Related projects
+
+[@microsoft/gulp-core-build](https://github.com/Microsoft/gulp-core-build) - An abstraction around gulp that adds simplified serial/parallel task execution and a formal base task interface.
+
+[typescript](https://github.com/Microsoft/typescript) - The TypeScript compiler.
+
+# License
+
+[MIT](https://github.com/Microsoft/gulp-core-build-typescript/blob/master/LICENSE)

package.json

@@ -9,20 +9,20 @@
     "@microsoft/gulp-core-build": "~0.9.0",
     "gulp": "~3.9.1",
     "gulp-cache": "~0.4.5",
-    "gulp-changed": "~1.3.0",
+    "gulp-changed": "~1.3.2",
     "gulp-plumber": "~1.1.0",
     "gulp-sourcemaps": "~1.6.0",
     "gulp-texttojs": "~1.0.3",
-    "gulp-typescript": "~2.12.1",
+    "gulp-typescript": "~2.13.6",
     "gulp-util": "~3.0.7",
-    "lodash": "~4.12.0",
+    "lodash": "~4.15.0",
     "md5": "~2.1.0",
     "merge2": "~1.0.2",
-    "object-assign": "~4.0.1",
+    "object-assign": "~4.1.0",
     "through2": "~2.0.1",
-    "tslint": "~3.14.0",
+    "tslint": "~3.15.1",
     "tslint-microsoft-contrib": "~2.0.10",
-    "typescript": "1.8.9"
+    "typescript": "~1.8.10"
   },
   "devDependencies": {
     "@microsoft/node-library-build": "~0.2.2"

src/TextTask.ts

@@ -2,6 +2,9 @@ import { GulpTask } from '@microsoft/gulp-core-build';
 import gulpType = require('gulp');
 
 export interface ITextTaskConfig {
+  /**
+   * Glob matches for files that should be converted into modules.
+   */
   textMatch?: string[];
 }
 

src/TypeScriptTask.ts

@@ -4,7 +4,7 @@ import ts = require('gulp-typescript');
 
 interface ITypeScriptErrorObject {
   diagnostic: {
-    messageText:  string | { messageText: string };
+    messageText: string | { messageText: string };
     code: number;
   };
   fullFilename: string;
@@ -17,10 +17,33 @@ interface ITypeScriptErrorObject {
 }
 
 export interface ITypeScriptTaskConfig {
+  /**
+   * Fails the build when errors occur.
+   * @default true
+   */
   failBuildOnErrors: boolean;
+
+  /**
+   * Glob matches for files to be included in the build.
+   */
   sourceMatch?: string[];
+
+  /**
+   * Glob matches for files to be passed through the build.
+   */
   staticMatch?: string[];
+
+  /**
+   * Optional override for a custom reporter object to be passed into the TypeScript compiler.
+   */
   reporter?: ts.Reporter;
+
+  /**
+   * Optional override for the TypeScript compiler.
+   */
+  /* tslint:disable:no-any */
+  typescript?: any;
+  /* tslint:enable:no-any */
 }
 
 export class TypeScriptTask extends GulpTask<ITypeScriptTaskConfig> {
@@ -30,15 +53,19 @@ export class TypeScriptTask extends GulpTask<ITypeScriptTaskConfig> {
     failBuildOnErrors: true,
     reporter: {
       error: (error: ITypeScriptErrorObject): void => {
+        const filename: string = error.relativeFilename || error.fullFilename;
+        const line: number = error.startPosition ? error.startPosition.line : 0;
+        const character: number = error.startPosition ? error.startPosition.character : 0;
+        const code: number = error.diagnostic.code;
         const errorMessage: string = (typeof error.diagnostic.messageText === 'object') ?
           (error.diagnostic.messageText as { messageText: string }).messageText :
           error.diagnostic.messageText as string;
 
         this.fileError(
-          error.relativeFilename || error.fullFilename,
-          error.startPosition.line,
-          error.startPosition.character,
-          `TS${error.diagnostic.code}`,
+          filename,
+          line,
+          character,
+          'TS' + code,
           errorMessage);
       }
     },
@@ -73,7 +100,8 @@ export class TypeScriptTask extends GulpTask<ITypeScriptTaskConfig> {
 
     const tsCompilerOptions: ts.Params = assign({}, tsConfig.compilerOptions, {
       module: 'commonjs',
-      sortOutput: true
+      sortOutput: true,
+      typescript: this.taskConfig.typescript
     });
 
     const tsProject: ts.Project = this._tsProject = this._tsProject || ts.createProject(tsCompilerOptions);