eps1lon / dtslint

WIP: A fork of Microsoft/dtslint whose goal it is to adhere to semver (see monorepo branch and issues)

dtslint tests a TypeScript declaration file for style and correctness. It will install typescript and tslint for you, so this is the only tool you need to test a type definition.

Lint rules new to dtslint are documented in the docs directory.

Setup

If you are working on DefinitelyTyped, read the DefinitelyTyped README.

If you are writing the library in TypeScript, don't use dtslint. Use --declaration to have type definitions generated for you.

If you are a library author, read below.

Add types for a library (not on DefinitelyTyped)

dts-gen may help, but is not required.

Create a types directory. (Name is arbitrary.) Add "types": "types" to your package.json. Read more on bundling types here.

types/index.d.ts

Only index.d.ts needs to be published to NPM. Other files are just for testing. Write your type definitions here. Refer to the handbook or dts-gen's templates for how to do this.

types/tsconfig.json

{
    "compilerOptions": {
        "module": "commonjs",
        "lib": ["es6"],
        "noImplicitAny": true,
        "noImplicitThis": true,
        "strictNullChecks": true,
        "strictFunctionTypes": true,
        "noEmit": true,

        // If the library is an external module (uses `export`), this allows your test file to import "mylib" instead of "./index".
        // If the library is global (cannot be imported via `import` or `require`), leave this out.
        "baseUrl": ".",
        "paths": { "mylib": ["."] }
    }
}

You may extend "lib" to, for example, ["es6", "dom"] if you need those typings. You may also have add "target": "es6" if using certain language features.

types/tslint.json

If you are using the default rules, this is optional.

If present, this will override dtslint's default settings. You can specify new lint rules, or disable some. An example:

{
    "extends": "dtslint/dtslint.json", // Or "dtslint/dt.json" if on DefinitelyTyped
    "rules": {
        "semicolon": false,
        "indent": [true, "tabs"]
    }
}

types/test.ts

You can have any number of test files you want, with any names. See below on what to put in them.

Write tests

A test file should be a piece of sample code that tests using the library. Tests are type-checked, but not run. To assert that an expression is of a given type, use $ExpectType. To assert that an expression causes a compile error, use $ExpectError. (Assertions will be checked by the expect lint rule.)

import { f } from "my-lib"; // f is(n: number) => void

// $ExpectType void
f(1);

// Can also write the assertion on the same line.
f(2); // $ExpectType void

// $ExpectError
f("one");

Specify a TypeScript version

Normally packages will be tested using TypeScript 2.0. To use a newer version, specify it by including a comment like so:

// TypeScript Version: 2.1

For DefinitelyTyped packages, this should go just under the header (on line 5). For bundled typings, this can go on any line (but should be near the top).

Run tests

• npm install --save-dev dtslint
• Add to your package.json scripts: "dtslint": "dtslint types"
• npm run dtslint

Contributing

Build

npm link . # Global 'dts-lint' should now refer to this.
npm run watch

Test

Use npm run test to run all tests. To run a single test: node node_modules/tslint/bin/tslint --rules-dir bin/rules --test test/expect.

Publish

production branch

npm run push-production

This script merges changes from master into production and updates the bin/ directory. The production branch is a dependency of DefinitelyTyped and types-publisher.

NPM

1. Update package.json
2. Follow publish steps except for the git push at the end.
3. Make sure you are logged in to npm as typescript.
4. npm publish

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

dtslint's Issues

Missing tests

Tracking issue for missing tests:

• tslint-rule-no-declare-current-package
• tslint-rule-no-outside-dependency
• tslint-rule-no-padding
  • tests that display why the bump to 2.9 was made
• tslint-rule-no-redundant-jsdoc
• tslint-no-self-import

Changes

Tracking issue for changes to the upstream that go beyond just porting to a monorepo:

• granular version check for provided typescript module
  • each rule has its own typescript peerDependency
• tests from #1
• Removed unified-signatures from dtslint.json no implementation for this rule found
• Fixed no-redundant-jsdoc:
  • filename was noRedundantJsdoc2Rule implying no-redundant-jsdoc2 but the rule name was set to no-redundant-jsdoc
  • no-redundant-jsdoc-2 was enabled while there exists no implementation
  • no-redundant-jsdoc was disabled while there exists a implementation
• expectRule:
  • removed functionality that looked for the minimal working ts version
    • functionality is not very well documented
    • I also believe that this is something a wrapper for the cli should do (and use binary search)
    • otherwise this is already given by the ability to specify multiple ts version

WIP

• rewrite dtslint-cli with the following goal:
  • consistent setup with reproducible output:
    • for each ts version create a package from which tslint is run
    • requires tslint version finder for ts version
  • usage with conflicting ts version in devDependencies
  • cli includes two passes over the codebase:
    • one tslint call without expect using own dependencies
    • one tslint call using the ts version described in the typings header and expect