CI品質ゲート

check、coverage、lintを1つのジョブにまとめて、ドキュメントを劣化させるPRを失敗させます。

ジョブの例

.github/workflows/docs-quality.yml
# .github/workflows/docs-quality.yml
name: Docs quality gate
on: pull_request

jobs:
  docs-quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - name: Docs quality gate
        run: |
          npx nestjs-docfy check
          npx nestjs-docfy coverage --min 90
          npx nestjs-docfy lint

checkは、@WithDocs()が付いたコントローラーにコンパニオンファイルがない場合、または前回のgenerate以降にメソッドが追加された場合に失敗します。coverage --min 90は、エンドポイントの90%未満しかドキュメント化されていない場合にビルドを失敗させます。lintは、すでにドキュメント化されている内容の品質を判定します。ApiOperationのsummaryの欠落、@Body()を持つのに400レスポンスがないエンドポイント、説明のないApiBodyです。3つのコマンドはいずれも問題を見つけるとコード1で終了し、パイプラインを失敗させます。

失敗時の出力

npx nestjs-docfy check
✖ UsersController: undocumented methods: updateProfile, deleteAccount
  → run nestjs-docfy generate --force to merge new methods

✖ 2 controller(s) out of sync.
npx nestjs-docfy coverage --min 90
Controllers: 42
Endpoints: 187

Documented: 174
Missing docs: 13

Coverage: 93.0%
npx nestjs-docfy lint
✖ POST /users
  Missing 400 response

✖ GET /users
  Missing operation summary

✖ PATCH /users/:id
  Missing request body description

✖ 3 issue(s) found.

npmスクリプトとして

package.json
{
  "scripts": {
    "docs:check": "nestjs-docfy check",
    "docs:coverage": "nestjs-docfy coverage --min 90",
    "docs:lint": "nestjs-docfy lint"
  }
}