no-bad-reference: Avoid <reference types> of the current package

docs/no-bad-reference.md

@@ -1,7 +1,8 @@
 # no-bad-reference
 
 (This rule is specific to DefinitelyTyped.)
-Avoid using `<reference path>`.
+Avoid using `<reference path>` to reference other packages.
+Do use `<reference path>` to reference a file in the current package, though this is usually unnecessary.
 
 **Bad**:
 
@@ -25,4 +26,17 @@ If not, use `<reference types>` instead:
 /// <reference types="foo" />
 ```
 
-The only time `<reference path>` should be necessary if for global (not module) libraries that are separated into multiple files; the index file must include references to the others to bring them into the compilation.
+The only time `<reference path>` should be necessary is for global (not module) libraries that are separated into multiple files; the index file must include references to the others to bring them into the compilation.
+
+**Bad**:
+```ts
+/// <reference types="this-package-name" />
+```
+
+ **Good**:
+
+Usually intra-package references can simply be omitted. If not, use a relative path.
+
+```ts
+/// <reference path="./index.d.ts" />
+```

src/rules/noBadReferenceRule.ts

@@ -1,3 +1,5 @@
+import assert = require("assert");
+import { basename, dirname } from "path";
 import * as Lint from "tslint";
 import * as ts from "typescript";
 
@@ -18,7 +20,15 @@ export class Rule extends Lint.Rules.AbstractRule {
 		"Don't use <reference path> to reference another package. Use an import or <reference types> instead.");
 	static FAILURE_STRING_REFERENCE_IN_TEST = failure(
 		Rule.metadata.ruleName,
-		"Don't use <reference path> in test files. Use <reference types> or include the file in 'tsconfig.json'.");
+		"Don't use <reference path> in test files. " +
+		"Use <reference types> for external dependencies. " +
+		"To reference a file in this package, include it in 'tsconfig.json'.");
+	static FAILURE_STRING_TYPE_REFERENCE_TO_SELF(packageName: string): string {
+		return failure(
+			Rule.metadata.ruleName,
+			`Type reference to ${packageName} refers to the current package.\n` +
+			"normally this can simply be removed, or you should use a '<reference path>' instead.");
+	}
 
 	apply(sourceFile: ts.SourceFile): Lint.RuleFailure[] {
 		return this.applyWithFunction(sourceFile, walk);
@@ -27,6 +37,14 @@ export class Rule extends Lint.Rules.AbstractRule {
 
 function walk(ctx: Lint.WalkContext<void>): void {
 	const { sourceFile } = ctx;
+
+	for (const ref of sourceFile.typeReferenceDirectives) {
+		const packageName = getCurrentPackageName(sourceFile.fileName);
+		if (ref.fileName === packageName) {
+			ctx.addFailure(ref.pos, ref.end, Rule.FAILURE_STRING_TYPE_REFERENCE_TO_SELF(basename(packageName)));
+		}
+	}
+
 	for (const ref of sourceFile.referencedFiles) {
 		if (sourceFile.isDeclarationFile) {
 			if (ref.fileName.startsWith("..")) {
@@ -37,3 +55,12 @@ function walk(ctx: Lint.WalkContext<void>): void {
 		}
 	}
 }
+
+function getCurrentPackageName(fileName: string): string {
+	let dir = dirname(fileName);
+	while (basename(dirname(dir)) !== "types") {
+		assert(dir !== "");
+		dir = dirname(dir);
+	}
+	return basename(dir);
+}

test/no-bad-reference/test.ts.lint

@@ -4,4 +4,4 @@
 /// <reference path="foo" />
                      ~~~ [0]
 
-[0]: Don't use <reference path> in test files. Use <reference types> or include the file in 'tsconfig.json'. See: https://github.com/Microsoft/dtslint/blob/master/docs/no-bad-reference.md
+[0]: Don't use <reference path> in test files. Use <reference types> for external dependencies. To reference a file in this package, include it in 'tsconfig.json'. See: https://github.com/Microsoft/dtslint/blob/master/docs/no-bad-reference.md