docfy coverage

エンドポイントのうち何パーセントがドキュメント化されているかを計測します。客観的な品質指標やCIゲートとして有用です。

使い方

bash
npx nestjs-docfy coverage [options]

オプション

OptionDefaultDescription
--root <path>.Project root directory
--tsconfig <path>auto-detectedPath to tsconfig.json
--pattern <glob>**/*.controller.tsGlob pattern to find controllers
--format <format>ts探索するdocsファイルの形式: tsまたはjs
--min <percent>none必要な最小カバレッジ(0〜100)。下回ると1で終了します
--jsonfalse整形されたテキストではなく、単一のJSONオブジェクトを出力します: カバレッジレポートに加えてminとpassedを含みます。
--quietfalseSuppress all output except errors

出力例

text
Controllers: 42
Endpoints: 187

Documented: 174
Missing docs: 13

Coverage: 93.0%

CIで最小値を強制する

bash
npx nestjs-docfy coverage --min 95

カバレッジが--minを下回ると、コマンドはコード1で終了し、ビルドを失敗させます。

.github/workflows/*.yml
# GitHub Actions example
- name: Enforce documentation coverage
  run: npx nestjs-docfy coverage --min 95

またはnpmスクリプトとして:

json
{
  "scripts": {
    "docs:coverage": "nestjs-docfy coverage --min 95"
  }
}

PRボット

nest-docfy自身の.github/workflows/pr-check.ymlが実例です。すべてのPRに対しプロジェクトにcheck --jsonとcoverage --json --minを実行し、単一のサマリーコメントを投稿(スパムせず更新のみ)します。すべて--json出力とネイティブのfetchによるGitHub REST APIの呼び出しだけで構築されており、追加の依存関係はありません。