ts-comment-scanner

日本語 | English | 📘 プロジェクトサイト / Project site

日本語

TypeScript と JavaScript のコメントを一覧し、不要なものを安全に削除する CLI です。インストールせずに npx で実行します。コーディングエージェントがコードに書き足した「レビューの指摘に従い修正」のような経緯のコメントを、エージェントが触ったファイルから取り除く用途を想定しています。

# 未コミットの変更があるファイルで、削除されるコメントを確かめる
npx @kongyo2/ts-comment-scanner --remove --dry-run --diff HEAD

# 削除する
npx @kongyo2/ts-comment-scanner --remove --diff HEAD

• コメントは TypeScript のパーサーで取り出すので、文字列・テンプレートリテラル・正規表現・JSX テキストの中の // や /* をコメントと取り違えません。
• @ts-expect-error・eslint-disable・webpackChunkName: のように、消すとビルドやリントの結果が変わるコメント(ディレクティブ)と、ライセンス表記は残します。
• 残したディレクティブは、削除の前後で同じコードに適用されます。eslint-disable-next-line や /* c8 ignore next 3 */ が数える行は動かしません。
• --diff を付けると、git で変更があったファイルだけを対象にします。
• 結果はテキスト・JSON・GitHub Actions のアノテーションで出力します。--fail-on-comment を付けると、コメントがあるときに CI を失敗させられます。

使い方

コメントを一覧する

src/range.ts を例にします。

import { normalize } from "./normalize.js";

// レビューの指摘に従い、空の範囲では HEAD を返すようにした
export function resolveRange(input: string) {
  if (input === "") return "HEAD"; // 指摘どおり修正
  // @ts-expect-error 上流から null が渡ることがある
  return normalize(input);
}

パスを渡すと、コメントを ファイル:行:桁 の位置つきで一覧します。ディレクティブには [@ts-expect-error] のように名前が付きます。パスを省略すると、カレントディレクトリが対象です。

$ npx @kongyo2/ts-comment-scanner src
src/range.ts:3:1 [line] // レビューの指摘に従い、空の範囲では HEAD を返すようにした
src/range.ts:5:36 [line] // 指摘どおり修正
src/range.ts:6:3 [line] [@ts-expect-error] // @ts-expect-error 上流から null が渡ることがある

3 comments across 1 file

コメントを削除する

--remove --dry-run で、ファイルを変えずに削除対象を確かめます。

$ npx @kongyo2/ts-comment-scanner --remove --dry-run src
src/range.ts: would remove 2 (kept 1)

Would remove 2 comments across 1 file. Kept 1 protected comment.

--dry-run を外すと削除します。経緯のコメントが消え、@ts-expect-error は残ります。

import { normalize } from "./normalize.js";

export function resolveRange(input: string) {
  if (input === "") return "HEAD";
  // @ts-expect-error 上流から null が渡ることがある
  return normalize(input);
}

ディレクティブも消すときは --remove-directives、ライセンス表記も消すときは --remove-legal を付けます。プロジェクト独自のツールが読む目印のように、ほかにも残したいコメントがあれば --keep に正規表現で指定します。

npx @kongyo2/ts-comment-scanner --remove --keep "@skipMangle" --keep "^// INJECT" src

何を残し、削除後のコードをどう整えるかは削除の動作にまとめています。

変更したファイルだけを対象にする

--diff <range> を付けると、git が変更ありと報告するファイルだけを対象にします。<range> には git diff に渡すリビジョンをそのまま書きます。

• HEAD のようにリビジョンを 1 つだけ書くと、作業ツリーと比べます。まだ追跡していない新しいファイルも対象です(.gitignore に一致するものは除きます)。
• main..HEAD や main...HEAD のように書くと、コミット同士を比べます。

# 未コミットの変更があるファイルで、削除対象を確かめる
npx @kongyo2/ts-comment-scanner --remove --dry-run --diff HEAD

# ブランチで変更したファイルからコメントを削除する
npx @kongyo2/ts-comment-scanner --remove --diff main...HEAD

範囲内で削除されたファイルは対象外になり、名前を変えたファイルは新しいパスで扱います。--diff は、コマンドラインで直接指定したファイルにも適用します。git は、最初に指定したパスがあるリポジトリで実行します。

CI で使う

--format github を付けると、コメントを GitHub Actions のアノテーションとして出力し、PR の該当行に表示します。--fail-on-comment を付けると、コメントを 1 件でも報告したときに終了コード 1 で終わります。

- name: Check for stray comments
  run: npx @kongyo2/ts-comment-scanner --format github --skip-directives --fail-on-comment src

バージョンを固定する

npx @kongyo2/ts-comment-scanner@<バージョン> のようにバージョンを付けると、そのバージョンで実行します。プロジェクトの devDependencies に入れておくと、npm scripts と npx ts-comment-scanner が、入れたバージョンで動きます。

npm install --save-dev @kongyo2/ts-comment-scanner

削除の動作

--remove が削除するのは、TypeScript のパーサーがコメントと判定した範囲だけです。

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗