docs/npm-naming.md

@@ -2,7 +2,8 @@
 
 (This rule is specific to DefinitelyTyped.)
 
-Checks that the name of the type package matches a source package on npm.
+## Name checks
+In 'name-only' mode, checks that the name of the type package matches a source package on npm.
 
 ---
 
@@ -12,7 +13,7 @@ Checks that the name of the type package matches a source package on npm.
 // Type definitions for browser-only-package 1.2
 ```
 
-* If the package is really browser-only, you have mark it with "non-npm package"
+* If the package is really browser-only, you have to mark it with "non-npm package".
 * If the package actually has a matching npm package, you must use that name.
 
 **Good**:
@@ -37,6 +38,10 @@ Checks that the name of the type package matches a source package on npm.
 // Type definitions for some-package 10.1
 ```
 
+## Code checks
+
+In 'code' mode, in addition to the name checks, this rule also checks that the source JavaScript code matches the declaration file for npm packages.
+
 ---
 
 **Bad**:
@@ -55,14 +60,78 @@ module.exports = function () {
 };
 ```
 
-* A commonjs module.exports assignment is not really an export default, and the d.ts should use the `export =` syntax.
-* `export default` can only be used to export a commonjs `module.exports =` when you have `esModuleInterop` turned on, which not everybody does.
+* A CommonJs module.exports assignment is not really an export default, and the d.ts should use the [`export =`](https://www.typescriptlang.org/docs/handbook/modules.html#export--and-import--require) syntax.
+* `export default` can only be used to export a CommonJs `module.exports =` when you have `esModuleInterop` turned on, which not everybody does.
 
 **Good**:
 
 `foo/index.d.ts`:
 
 ```ts
-function f(): void;
+declare function f(): void;
 export = f;
 ```
+
+---
+
+**Bad**:
+
+`foo/index.d.ts`:
+
+```ts
+export class C {}
+```
+
+`foo/index.js`:
+
+```js
+module.exports = class C {}
+```
+
+* The CommonJs module is a class, which means it can be constructed, like this:
+```js
+var C = require('foo');
+var x = new C();
+```
+However, the way `class C` is exported in the d.ts file (using an export declaration) means it can only be used like this:
+```ts
+var foo = require('foo');
+var x = new foo.C(); 
+```
+
+* The d.ts should use [`export =`](https://www.typescriptlang.org/docs/handbook/modules.html#export--and-import--require)
+syntax to match the CommonJs module behavior.
+
+**Good**:
+
+`foo/index.d.ts`:
+
+```ts
+declare class C {}
+export = C;
+```
+
+* If you need to use `export =` syntax as in the example above, and the source JavaScript also exports some properties,
+you might need to use [*declaration merging*](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#merging-namespaces-with-classes-functions-and-enums) in your d.ts. Example:
+
+**JavaScript**:
+
+`foo/index.js`:
+
+```js
+function foo() {};
+foo.bar = "Exported property";
+module.exports = foo; // module.exports is a function, but it also has a property called `bar`
+```
+
+**Declaration**:
+
+`foo/index.d.ts`:
+
+```ts
+declare function foo(): void;
+declare namespace foo {
+    var bar: string;
+}
+export = foo;
+```

package.json

@@ -1,6 +1,6 @@
 {
   "name": "dtslint",
-  "version": "2.0.5",
+  "version": "2.0.6",
   "description": "Runs tests on TypeScript definition files",
   "files": [
     "bin",
@@ -28,19 +28,19 @@
   },
   "dependencies": {
     "definitelytyped-header-parser": "3.8.2",
-    "dts-critic": "^2.2.4",
+    "dts-critic": "^3.0.0",
     "fs-extra": "^6.0.1",
     "strip-json-comments": "^2.0.1",
     "tslint": "5.14.0",
     "typescript": "next"
   },
   "devDependencies": {
     "@types/fs-extra": "^5.0.2",
-    "@types/node": "^7.10.7",
+    "@types/node": "12.0.x",
     "@types/strip-json-comments": "^0.0.28"
   },
   "engines": {
-    "node": ">=6.10.0"
+    "node": ">=12.0.0"
   },
   "license": "MIT"
 }