new rule 'const-parameters'

Fixes: #34

Author: ajafff

README.md

@@ -46,6 +46,7 @@ Now configure some of the new rules.
 
 Rule | Description
 ---- | ----
+[const-parameters](https://github.com/ajafff/tslint-consistent-codestyle/blob/master/docs/const-parameters.md) | Declare parameters as `const` with JsDoc `/** @const */`
 [early-exit](https://github.com/ajafff/tslint-consistent-codestyle/blob/master/docs/early-exit.md) | Recommends to use an early exit instead of a long `if` block.
 [ext-curly](https://github.com/ajafff/tslint-consistent-codestyle/blob/master/docs/ext-curly.md) |Enforces where to consistently use curly braces where not strictly necessary.
 [naming-convention](https://github.com/ajafff/tslint-consistent-codestyle/blob/master/docs/naming-convention.md) | Fine grained configuration to enfoce consistent naming for almost everything. E.g. variables, functions, classes, methods, parameters, enums, etc.

docs/const-parameters.md

@@ -0,0 +1,29 @@
+## ext-curly
+
+Disallows reassigning parameters that are considered constants. This rule is similar to tslint's [`no-parameter-reassignent`](https://palantir.github.io/tslint/rules/no-parameter-reassignment/) but allows you to explicitly declare which parameter is a constant with JsDoc `/** @const */`
+
+```ts
+function fn(/**@const*/foo, bar) {
+  foo++; // error on this line
+  bar++; // no error
+}
+
+class C {
+  constructor(/** @const */ public foo) {
+    foo++; // error on this line
+    this.foo++; // no error on this line, because only parameters are checked by this rule
+  }
+}
+
+function fn(/**@constant*/foo) { // also works with @constant tag
+  foo++; // error on this line
+}
+
+function fn({ // also works with destructured parameters
+  /**@const*/ foo,
+  baz: /**@const*/ bar,
+}) {
+  foo++; // error on this line
+  bar++; // error on this line
+}
+```

package.json

@@ -31,7 +31,7 @@
   "license": "MIT",
   "dependencies": {
     "tslib": "^1.7.1",
-    "tsutils": "^2.8.2"
+    "tsutils": "^2.11.0"
   },
   "devDependencies": {
     "coveralls": "^2.13.0",

rules/constParametersRule.ts

@@ -0,0 +1,62 @@
+/**
+ * @license
+ * Copyright 2017 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 { collectVariableUsage, getDeclarationOfBindingElement, isReassignmentTarget, getJsDoc, parseJsDocOfNode } from 'tsutils';
+import * as ts from 'typescript';
+import * as Lint from 'tslint';
+
+export class Rule extends Lint.Rules.AbstractRule {
+    public apply(sourceFile: ts.SourceFile): Lint.RuleFailure[] {
+        return this.applyWithFunction(sourceFile, walk);
+    }
+}
+
+function walk(ctx: Lint.WalkContext<void>): void {
+    collectVariableUsage(ctx.sourceFile).forEach((variable, identifier) => {
+        if (!isParameter(identifier.parent!) || !isConst(identifier, ctx.sourceFile))
+            return;
+        for (const use of variable.uses)
+            if (isReassignmentTarget(use.location))
+                ctx.addFailureAtNode(use.location, `Cannot reassign constant parameter '${identifier.text}'.`);
+    });
+}
+
+function isParameter(node: ts.Node): boolean {
+    switch (node.kind) {
+        case ts.SyntaxKind.Parameter:
+            return true;
+        case ts.SyntaxKind.BindingElement:
+            return getDeclarationOfBindingElement(<ts.BindingElement>node).kind === ts.SyntaxKind.Parameter;
+        default:
+            return false;
+    }
+}
+
+function isConst(name: ts.Identifier, sourceFile: ts.SourceFile) {
+    if (name.parent!.kind === ts.SyntaxKind.Parameter)
+        return getJsDoc(name.parent!, sourceFile).some(jsDocContainsConst);
+    // destructuring
+    return parseJsDocOfNode(name, true, sourceFile).some(jsDocContainsConst);
+}
+
+function jsDocContainsConst(jsDoc: ts.JSDoc): boolean {
+    if (jsDoc.tags !== undefined)
+        for (const tag of jsDoc.tags)
+            if (tag.tagName.text === 'const' || tag.tagName.text === 'constant')
+                return true;
+    return false;
+}

test/rules/const-parameters/default/test.ts.lint

@@ -0,0 +1,63 @@
+function fn(foo) {
+    foo++;
+}
+function fn(/**@constant*/foo) {
+    foo++;
+    ~~~ [err % ('foo')]
+}
+function fn(/** @const */ foo, bar) {
+    foo++;
+    ~~~ [err % ('foo')]
+    bar++;
+}
+function fn(/** @const */ foo, bar) {
+    bar = foo;
+}
+function fn(/**@const some text*/foo) {
+    foo++;
+    ~~~ [err % ('foo')]
+}
+function fn({/**@const*/foo}) {
+    foo++;
+    ~~~ [err % ('foo')]
+}
+function fn({bar: /**@const*/foo}) {
+    foo++;
+    ~~~ [err % ('foo')]
+}
+function fn({/**@const*/foo, bar}) {
+    foo++;
+    ~~~ [err % ('foo')]
+    bar++;
+}
+class Clazz {
+    constructor(/**@const*/foo, /**@const*/ private bar, /**@const*/ readonly baz) {
+        foo++;
+        ~~~ [err % ('foo')]
+        bar++;
+        ~~~ [err % ('bar')]
+        baz++;
+        ~~~ [err % ('baz')]
+        this.bar++;
+        this.baz++;
+    }
+}
+function fn(
+    /** some description */
+    /** @constant */
+    foo,
+) {
+    foo++;
+    ~~~ [err % ('foo')]
+}
+function fn(/** foo */foo) {
+    foo++;
+}
+function fn(/**const*/foo) {
+    foo++;
+}
+function fn(/**@param*/foo) {
+    foo++;
+}
+
+[err]: Cannot reassign constant parameter '%s'.

test/rules/const-parameters/default/tslint.json

@@ -0,0 +1,6 @@
+{
+  "rulesDirectory": "../../../../rules",
+  "rules": {
+    "const-parameters": true
+  }
+}