build: detect todos in public comments (#4059)

* build: detect todos in public comments

* Creates a naive rule that checks all multi-line comments and reports failures once it detects TODOs inside of it.

* This means that TODOs always need to placed inside of single-line comments.

Fixes #4026

Author: devversion

src/lib/core/observe-content/observe-content.spec.ts

@@ -2,10 +2,8 @@ import {Component} from '@angular/core';
 import {async, TestBed} from '@angular/core/testing';
 import {ObserveContentModule} from './observe-content';
 
-/**
- * TODO(elad): `ProxyZone` doesn't seem to capture the events raised by
- * `MutationObserver` and needs to be investigated
- */
+// TODO(elad): `ProxyZone` doesn't seem to capture the events raised by
+// `MutationObserver` and needs to be investigated
 
 describe('Observe content', () => {
   beforeEach(async(() => {

src/lib/select/select.ts

@@ -654,7 +654,6 @@ export class MdSelect implements AfterContentInit, OnDestroy, OnInit, ControlVal
   /**
    * Sets the `multiple` property on each option. The promise is necessary
    * in order to avoid Angular errors when modifying the property after init.
-   * TODO: there should be a better way of doing this.
    */
   private _setOptionMultiple() {
     if (this.multiple) {

src/lib/tabs/tab-body.ts

@@ -153,11 +153,10 @@ export class MdTabBody implements OnInit, AfterViewChecked, AfterContentChecked
    * computed style (with Angular > 2.3.0). This can alternatively be determined by checking the
    * transform: canBeAnimated = getComputedStyle(element) !== '', however document.contains should
    * be faster since it doesn't cause a reflow.
-   *
-   * TODO: This can safely be removed after we stop supporting Angular < 2.4.2. The fix landed via
-   * https://github.com/angular/angular/commit/21030e9a1cf30e8101399d8535ed72d847a23ba6
    */
   ngAfterContentChecked() {
+    // TODO: This can safely be removed after we stop supporting Angular < 2.4.2. The fix landed via
+    // https://github.com/angular/angular/commit/21030e9a1cf30e8101399d8535ed72d847a23ba6
     if (!this._canBeAnimated) {
       this._canBeAnimated = document.body.contains(this._elementRef.nativeElement);
 

tools/tslint-rules/noExposedTodoRule.js

@@ -0,0 +1,34 @@
+const ts = require('typescript');
+const utils = require('tsutils');
+const Lint = require('tslint');
+
+const ERROR_MESSAGE =
+    'A TODO may only appear in inline (//) style comments. ' +
+    'This is meant to prevent a TODO from being accidentally included in any public API docs.';
+
+/**
+ * Rule that walks through all comments inside of the library and adds failures when it
+ * detects TODO's inside of multi-line comments. TODOs need to be placed inside of single-line
+ * comments.
+ */
+class Rule extends Lint.Rules.AbstractRule {
+
+  apply(sourceFile) {
+    return this.applyWithWalker(new NoExposedTodoWalker(sourceFile, this.getOptions()));
+  }
+}
+
+class NoExposedTodoWalker extends Lint.RuleWalker {
+
+  visitSourceFile(sourceFile) {
+    utils.forEachComment(sourceFile, (fullText, commentRange) => {
+      let isTodoComment = fullText.substring(commentRange.pos, commentRange.end).includes('TODO');
+
+      if (commentRange.kind === ts.SyntaxKind.MultiLineCommentTrivia && isTodoComment) {
+        this.addFailureAt(commentRange.pos, commentRange.end - commentRange.pos, ERROR_MESSAGE);
+      }
+    });
+  }
+}
+
+exports.Rule = Rule;

tslint.json

@@ -1,5 +1,8 @@
 {
-  "rulesDirectory": ["node_modules/tslint-no-unused-var"],
+  "rulesDirectory": [
+    "./node_modules/tslint-no-unused-var/", 
+    "./tools/tslint-rules/"
+  ],
   "rules": {
     "max-line-length": [true, 100],
     // Disable this flag because of SHA tslint#48b0c597f9257712c7d1f04b55ed0aa60e333f6a
@@ -26,6 +29,7 @@
     "no-unused-expression": true,
     "no-unused-var": [true, {"ignore-pattern": "^(_.*)$"}],
     "no-var-keyword": true,
+    "no-exposed-todo": true,
     "no-debugger": true,
     "one-line": [
       true,