typescript-eslintのban-ts-commentルールについて

はじめに

この記事ではtypescript-eslintのルールのうちban-ts-commentについて解説します。
typescript-eslintの他のルールについても別記事で解説し、最終的にReact開発を行うにあたって最適なルール設定を構築することを目的としています。

ルールについて

ban-ts-commentはTypeScriptが提供するコンパイルエラーの抑制などのコメントに対する制限を行うルールです。"plugin:@typescript-eslint/recommended"で有効になります。
対象のコメントは4種類あります。
1つ目は@ts-expect-errorです。指定した箇所のTypeScriptのコンパイルエラーを抑制し、コンパイルエラーがない場合にコメントがある場合はエラーを発生させるコメントです。

// 引数を全て足し合わせる関数
const sum = (...args: number[]): number => {
  return args.reduce((sum, arg) => {
    return sum + arg
  }, 0);
};

// @ts-expect-error: エラーが抑制される
sum(1, 2, '3');

// @ts-expect-error: 型が正しいのでエラーが発生する
sum(1, 2, 3);

前者はnumber型を期待する箇所にstringが代入されることによるコンパイルエラーが発生するはずですが、@ts-expect-errorによってエラーが抑制されます。一方後者は正しくnumberを代入しているのでコンパイルエラーは生じませんが、@ts-expect-errorとコメントしているのでUnused '@ts-expect-error' directive.とエラーが発生します。directiveというのはこのようなエラーを抑制するコメントのことを指します。

2つ目は@ts-ignoreです。@ts-expect-errorからコンパイルエラーが生じなかった時にエラーを出す機能がないものです。

const sum = (...args: number[]): number => {
  return args.reduce((sum, arg) => {
    return sum + arg
  }, 0);
};

// @ts-ignore
sum(1, 2, '3');

// @ts-ignore
sum(1, 2, 3);

@ts-expect-errorとは異なり、どちらの呼び出しもエラーが発生しません。

3つ目は@ts-checkです。JavaScriptで書かれたファイルに対してTypeScriptのような型チェックをJSDocをもとに行わせるコメントです。
4つ目は@ts-nocheckです。@ts-checkによってファイル全体や、プロジェクト全体で型チェックが行われているときに、特定の箇所だけ型チェックを行わないようにするコメントです。

例としても利用しましたが、それらのコメントに対して@ts-expect-error: エラーが抑制されるのようにコメントを有効にしたことに対する説明を記述できます。

このルールはこのようなTypeScriptが提供するコメントの利用の可否や説明の記述の可否、正規表現で説明に対する制約を作れます。そしてそれは各コメントに対して設定できます。
デフォルトのオプションは以下のようになっています。

{
  "ts-expect-error": "allow-with-description",
  "ts-ignore": true,
  "ts-nocheck": true,
  "ts-check": false,
  "minimumDescriptionLength": 3
}

この設定では@ts-expect-errorは説明を添えた場合に利用することが可能に、@ts-ignoreと@ts-checkは利用が可能に、@ts-checkは利用が不可能に、そして全ての説明はminimumDescriptionLengthによって最低でも3文字以上書く必要があります。
デフォルトの設定にはありませんが、以下のようにすることで説明の表現を正規表現で指定することができます。

"ts-expect-error": {
  "descriptionFormat": "^: TS\\d+ because .+$"
}

この場合は下のように正規表現通りに書かない場合にルール違反となります。

// 正規表現に則っているのでエラーが出ない
// @ts-expect-error: TS1234 because the library definition is wrong

// 正規表現に則っていないのでエラーが出る
// @ts-expect-error: the library definition is wrong

ルールの採用について

このルールによって利用できるコメントのうち@ts-checkと@ts-nocheckはTypeScriptを利用する場合は不要なので無駄な利用を避けるために無効にしたいです。
また、他のコメントも最後の手段であり型安全性を損ねるので極力使いたく無いです。しかし、ライブラリの都合で@ts-expect-errorか@ts-ignoreは使わざるを得ない場合があります。そのため、どちらか片方はコメントで理由を書くことを条件に利用を許可します。@ts-expect-errorはそのライブラリの都合が解決した場合にエラーが発生してコメントを取り除けることを知らせてくれる恩恵があると考えられるので@ts-expect-errorに限って有効にしたいです。

つまりこのようにルールを作ります。

"@typescript-eslint/ban-ts-comment": [
  "error",
  {
    "ts-expect-error": "allow-with-description",
    "ts-ignore": false,
    "ts-nocheck": false,
    "ts-check": false,
  }
]