Add optional type information to rules (#1363)

Addresses #1323.

* Changed `Linter` to accept an optional program object in the constructor
  * Added helper functions for creating a program using a tsconfig and getting relevant files
* Created `TypedRule` class which receives the program object
  * Rules extending this class must implement `applyWithProgram`
  * `Linter` passes program to `TypedRule`s if available
  * Calling `apply` on a `TypedRule` throws an error
* Added `requiresTypeInfo` boolean to metadata
* Created `ProgramAwareRuleWalker` which walks with the program / typechecker
* Added cli options `--project` and `--type-check`
  * `--project` takes a `tsconfig.json` file
  * `--type-check` enables type checking and `TypedRule`s, requires `--project`
* Added an example `restrictPlusOperands` rule and tests that uses types

README.md

@@ -115,6 +115,8 @@ Options:
 -e, --exclude exclude globs from path expansion
 -t, --format output format (prose, json, verbose, pmd, msbuild, checkstyle) [default: "prose"]
 --test test that tslint produces the correct output for the specified directory
+--project path to tsconfig.json file
+--type-check enable type checking when linting a project
 -v, --version current version
 ```
 
@@ -182,6 +184,14 @@ tslint accepts the following command-line options:
  specified directory as the configuration file for the tests. See the
  full tslint documentation for more details on how this can be used to test custom rules.
 
+--project:
+ The location of a tsconfig.json file that will be used to determine which
+ files will be linted.
+
+--type-check
+ Enables the type checker when running linting rules. --project must be
+ specified in order to enable type checking.
+
 -v, --version:
  The current version of tslint.
 
@@ -214,6 +224,23 @@ const linter = new Linter(fileName, fileContents, options);
 const result = linter.lint();
 ```
 
+#### Type Checking
+
+To enable rules that work with the type checker, a TypeScript program object must be passed to the linter when using the programmatic API. Helper functions are provided to create a program from a `tsconfig.json` file. A project directory can be specified if project files do not lie in the same directory as the `tsconfig.json` file.
+
+```javascript
+const program = Linter.createProgram("tsconfig.json", "projectDir/");
+const files = Linter.getFileNames(program);
+const results = files.map(file => {
+ const fileContents = program.getSourceFile(file).getFullText();
+ const linter = new Linter(file, fileContents, options, program);
+ return result.lint();
+});
+```
+
+When using the CLI, the `--project` flag will automatically create a program from the specified `tsconfig.json` file. Adding `--type-check` then enables rules that require the type checker.
+
+
 Core Rules
 -----
 <sup>[back to ToC &uarr;](#table-of-contents)</sup>
@@ -313,6 +340,7 @@ Core rules are included in the `tslint` package.
  * `"jsx-double"` enforces double quotes for JSX attributes.
  * `"avoid-escape"` allows you to use the "other" quotemark in cases where escaping would normally be required. For example, `[true, "double", "avoid-escape"]` would not report a failure on the string literal `'Hello "World"'`.
 * `radix` enforces the radix parameter of `parseInt`.
+* `restrict-plus-operands` enforces the type of addition operands to be both `string` or both `number` (requires type checking).
 * `semicolon` enforces consistent semicolon usage at the end of every statement. Rule options:
  * `"always"` enforces semicolons at the end of every statement.
  * `"never"` disallows semicolons at the end of every statement except for when they are necessary.

src/language/rule/rule.ts

@@ -62,6 +62,11 @@ export interface IRuleMetadata {
  * An explanation of why the rule is useful.
  */
  rationale?: string;
+
+ /**
+ * Whether or not the rule requires type info to run.
+ */
+ requiresTypeInfo?: boolean;
 }
 
 export type RuleType = "functionality" | "maintainability" | "style" | "typescript";

src/language/rule/typedRule.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2016 Palantir Technologies, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as ts from "typescript";
+
+import {AbstractRule} from "./abstractRule";
+import {RuleFailure} from "./rule";
+
+export abstract class TypedRule extends AbstractRule {
+ public apply(sourceFile: ts.SourceFile): RuleFailure[] {
+ // if no program is given to the linter, throw an error
+ throw new Error(`${this.getOptions().ruleName} requires type checking`);
+ }
+
+ public abstract applyWithProgram(sourceFile: ts.SourceFile, program: ts.Program): RuleFailure[];
+}

src/language/walker/index.ts

@@ -16,6 +16,7 @@
  */
 
 export * from "./blockScopeAwareRuleWalker";
+export * from "./programAwareRuleWalker";
 export * from "./ruleWalker";
 export * from "./scopeAwareRuleWalker";
 export * from "./skippableTokenAwareRuleWalker";

src/language/walker/programAwareRuleWalker.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2016 Palantir Technologies, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as ts from "typescript";
+
+import {IOptions} from "../../lint";
+import {RuleWalker} from "./ruleWalker";
+
+export class ProgramAwareRuleWalker extends RuleWalker {
+ private typeChecker: ts.TypeChecker;
+
+ constructor(sourceFile: ts.SourceFile, options: IOptions, private program: ts.Program) {
+ super(sourceFile, options);
+
+ this.typeChecker = program.getTypeChecker();
+ }
+
+ public getProgram(): ts.Program {
+ return this.program;
+ }
+
+ public getTypeChecker(): ts.TypeChecker {
+ return this.typeChecker;
+ }
+}

src/rules.ts

@@ -16,3 +16,4 @@
  */
 
 export * from "./language/rule/abstractRule";
+export * from "./language/rule/typedRule";

src/rules/restrictPlusOperandsRule.ts

@@ -0,0 +1,65 @@
+/**
+ * @license
+ * Copyright 2016 Palantir Technologies, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as ts from "typescript";
+
+import * as Lint from "../lint";
+
+export class Rule extends Lint.Rules.TypedRule {
+ /* tslint:disable:object-literal-sort-keys */
+ public static metadata: Lint.IRuleMetadata = {
+ ruleName: "restrict-plus-operands",
+ description: "When adding two variables, operands must both be of type number or of type string.",
+ optionsDescription: "Not configurable.",
+ options: null,
+ optionExamples: ["true"],
+ type: "functionality",
+ requiresTypeInfo: true,
+ };
+ /* tslint:enable:object-literal-sort-keys */
+
+ public static MISMATCHED_TYPES_FAILURE = "Types of values used in '+' operation must match";
+ public static UNSUPPORTED_TYPE_FAILURE_FACTORY = (type: string) => `cannot add type ${type}`;
+
+ public applyWithProgram(sourceFile: ts.SourceFile, program: ts.Program): Lint.RuleFailure[] {
+ return this.applyWithWalker(new RestrictPlusOperandsWalker(sourceFile, this.getOptions(), program));
+ }
+}
+
+class RestrictPlusOperandsWalker extends Lint.ProgramAwareRuleWalker {
+ public visitBinaryExpression(node: ts.BinaryExpression) {
+ if (node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+ const tc = this.getTypeChecker();
+ const leftType = tc.typeToString(tc.getTypeAtLocation(node.left));
+ const rightType = tc.typeToString(tc.getTypeAtLocation(node.right));
+
+ const width = node.getWidth();
+ const position = node.getStart();
+
+ if (leftType !== rightType) {
+ // mismatched types
+ this.addFailure(this.createFailure(position, width, Rule.MISMATCHED_TYPES_FAILURE));
+ } else if (leftType !== "number" && leftType !== "string") {
+ // adding unsupported types
+ const failureString = Rule.UNSUPPORTED_TYPE_FAILURE_FACTORY(leftType);
+ this.addFailure(this.createFailure(position, width, failureString));
+ }
+ }
+
+ super.visitBinaryExpression(node);
+ }
+}

src/test.ts

@@ -20,7 +20,9 @@ import * as diff from "diff";
 import * as fs from "fs";
 import * as glob from "glob";
 import * as path from "path";
+import * as ts from "typescript";
 
+import {createCompilerOptions} from "./language/utils";
 import {LintError} from "./test/lintError";
 import * as parse from "./test/parse";
 import * as Linter from "./tslint";
@@ -46,17 +48,42 @@ export function runTest(testDirectory: string, rulesDirectory?: string | string[
 
  for (const fileToLint of filesToLint) {
  const fileBasename = path.basename(fileToLint, FILE_EXTENSION);
+ const fileCompileName = fileBasename.replace(/\.lint$/, "");
  const fileText = fs.readFileSync(fileToLint, "utf8");
  const fileTextWithoutMarkup = parse.removeErrorMarkup(fileText);
  const errorsFromMarkup = parse.parseErrorsFromMarkup(fileText);
 
+ const compilerOptions = createCompilerOptions();
+ const compilerHost: ts.CompilerHost = {
+ fileExists: () => true,
+ getCanonicalFileName: (filename: string) => filename,
+ getCurrentDirectory: () => "",
+ getDefaultLibFileName: () => ts.getDefaultLibFileName(compilerOptions),
+ getNewLine: () => "\n",
+ getSourceFile: function (filenameToGet: string) {
+ if (filenameToGet === this.getDefaultLibFileName()) {
+ const fileText = fs.readFileSync(ts.getDefaultLibFilePath(compilerOptions)).toString();
+ return ts.createSourceFile(filenameToGet, fileText, compilerOptions.target);
+ } else if (filenameToGet === fileCompileName) {
+ return ts.createSourceFile(fileBasename, fileTextWithoutMarkup, compilerOptions.target, true);
+ }
+ },
+ readFile: () => null,
+ useCaseSensitiveFileNames: () => true,
+ writeFile: () => null,
+ };
+
+ const program = ts.createProgram([fileCompileName], compilerOptions, compilerHost);
+ // perform type checking on the program, updating nodes with symbol table references
+ ts.getPreEmitDiagnostics(program);
+
  const lintOptions = {
  configuration: tslintConfig,
  formatter: "prose",
  formattersDirectory: "",
  rulesDirectory,
  };
- const linter = new Linter(fileBasename, fileTextWithoutMarkup, lintOptions);
+ const linter = new Linter(fileBasename, fileTextWithoutMarkup, lintOptions, program);
  const errorsFromLinter: LintError[] = linter.lint().failures.map((failure) => {
  const startLineAndCharacter = failure.getStartPosition().getLineAndCharacter();
  const endLineAndCharacter = failure.getEndPosition().getLineAndCharacter();

src/tsconfig.json

@@ -59,9 +59,11 @@
  "language/languageServiceHost.ts",
  "language/rule/abstractRule.ts",
  "language/rule/rule.ts",
+ "language/rule/typedRule.ts",
  "language/utils.ts",
  "language/walker/blockScopeAwareRuleWalker.ts",
  "language/walker/index.ts",
+ "language/walker/programAwareRuleWalker.ts",
  "language/walker/ruleWalker.ts",
  "language/walker/scopeAwareRuleWalker.ts",
  "language/walker/skippableTokenAwareRuleWalker.ts",
@@ -124,6 +126,7 @@
  "rules/orderedImportsRule.ts",
  "rules/quotemarkRule.ts",
  "rules/radixRule.ts",
+ "rules/restrictPlusOperandsRule.ts",
  "rules/semicolonRule.ts",
  "rules/switchDefaultRule.ts",
  "rules/trailingCommaRule.ts",