envdoc

envdoc

コード内で使用されている環境変数と .env.example の内容を比較します。

envdoc はソースファイルをスキャンして実際に読み取られている環境変数を特定し、見つかった名前を .env.example（または .env.sample）に記載された名前と比較します。使用されているが記載されていない変数、記載されているが一度も使用されていない変数、リポジトリの内容に不整合がないかを報告します。値がレポートに読み込まれることはありません。比較されるのは名前のみです。

機能

• 対象ディレクトリを走査し、.ts、.js、.mjs、.cjs、.py ファイルをスキャンします。
• node_modules、.git、dist、および fixtures という名前のディレクトリをスキップします。
• 次の形式の使用箇所を検出します。
  • process.env.NAME
  • process.env["NAME"] および process.env['NAME']
  • import.meta.env.NAME
  • os.environ["NAME"] および os.environ['NAME']
  • os.environ.get("NAME") および os.environ.get('NAME')
  • os.getenv("NAME") および os.getenv('NAME')
• リポジトリのルートにある .env.example を読み込みます。.env.example がない場合は .env.sample を読み込みます（最初に見つかったファイルが優先されます）。名前は KEY= または export KEY= の形式の行から取得します。= の左側のみを解析します。
• 決定的なレポートを出力します。検出結果は変数名順に並び、ファイルはソート順で走査され、タイムスタンプは含まれません。

名前のパターン：NAME は [A-Z][A-Z0-9_]* です。名前は大文字で始まり、大文字、数字、アンダースコアのみを含む必要があります。process.env の後に続く小文字で始まる名前は、仕様上無視されます。詳細は「制限事項」を参照してください。

インストール

npx @reneturcios/envdoc check

または、チェックアウトした作業ツリーから実行します。

npm install
npm run build
node dist/cli.js check .

CLI

# Check the current directory (human readable output)
npx @reneturcios/envdoc check

# Check another path
npx @reneturcios/envdoc check path/to/repo

# Machine readable output
npx @reneturcios/envdoc check path/to/repo --json

# Start the MCP server on stdio
npx @reneturcios/envdoc mcp

# Print the version
npx @reneturcios/envdoc --version

終了コード：

• 判定が IN-SYNC の場合は 0
• 判定が DRIFT の場合は 1
• 使用方法に誤りがある場合は 2
• 読み取り側が出力パイプを途中で閉じた場合は 141（シェルから見た SIGPIPE 相当）

出力例：

envdoc check .: DRIFT
  DRIFT: 2 used, 1 documented, 1 missing, 0 stale.
  counts: used 2, documented 1, missing 1, stale 0
  findings (2):
    [MEDIUM] app.ts:2 USED-NOT-DOCUMENTED FEATURE_CHARLIE is used in code but not documented in .env.example
    [INFO] VALUES-IGNORED Values are ignored: only variable names are compared, values are never read into the report
DRIFT: at least one medium or high finding. Document the missing vars or add an example file.

MCP サーバー

MCP クライアントの設定に追加します。

{
  "mcpServers": {
    "envdoc": {
      "command": "npx",
      "args": ["-y", "@reneturcios/envdoc", "mcp"]
    }
  }
}

ツール：

• check_env_docs：リポジトリのパスをスキャンし、レポート全体を JSON で返します。入力は単一のパス文字列です。レポートには判定、件数（used、documented、missing、stale）、検出結果、概要が含まれます。値は一切含まれません。

Docker：

docker run -i ghcr.io/cloudcorprecords/envdoc:0.1.0 mcp

ルール

ルール	深刻度	説明
USED-NOT-DOCUMENTED	medium	コードで使用されている変数が、サンプルファイルに記載されていません。検出結果には、最初に使用されたファイルと行が含まれます。変数ごとに1件の検出結果が出ます。
DOCUMENTED-NOT-USED	low	サンプルファイルに記載されている変数が、コードで一度も使用されていません。変数ごとに1件の検出結果が出ます。常に許可されるリストにある変数は除外されます。
NO-EXAMPLE	high	.env.example も .env.sample も見つからず、コードでは少なくとも1つの変数が使用されています。レポートごとに1件の検出結果が出ます。
VALUES-IGNORED	info	値がレポートに読み込まれることはありません。解析されるのは名前のみです。サンプルファイルでは、= の左側のみが読み込まれます。レポートごとに必ず1件の検出結果が出ます。

各レポートの件数：

• used：コード内で見つかった重複のない変数の数
• documented：サンプルファイルに記載された重複のない変数の数
• missing：使用されているが記載されていない変数の数（USED-NOT-DOCUMENTED の検出結果数）
• stale：記載されているが一度も使用されておらず、常に許可されるリストにもない変数の数（DOCUMENTED-NOT-USED の検出結果数）

常に許可されるリスト

リポジトリ内のコードで読み取られていなくても、これらの変数が記載されていないことを理由に警告されることはありません。これらは通常、アプリケーションコードではなく、プラットフォーム、ランタイム、または CI によって設定されます。

• NODE_ENV
• PORT
• HOST
• CI
• DEBUG

このリストは DOCUMENTED-NOT-USED ルールにのみ適用されます。これらの変数がコードで使用されていても記載されていない場合は、ほかの変数と同様に USED-NOT-DOCUMENTED として報告されます。

判定ルール

• IN-SYNC：medium または high の検出結果がありません。low および info の検出結果は含まれる場合があります。終了コードは 0 です。
• DRIFT：medium または high の検出結果が1件以上あります。終了コードは 1 です。

特例：サンプルファイルがなく、コード内でも変数がまったく使用されていない場合、判定は IN-SYNC となり、すべての検出結果の深刻度は info となり、概要は "no env usage found" になります。

サンプルファイルがなく、コードで変数が使用されている場合、判定は DRIFT となり、深刻度が high の NO-EXAMPLE 検出結果と、不足している変数ごとの USED-NOT-DOCUMENTED 検出結果が出ます。

制限事項

• 名前パターンのみを対象とし、値は読み取りません。envdoc は名前のみを比較します。環境変数の値を読み取ったり、保存したり、出力したりすることはありません。サンプルファイルについては、各行の = の左側のみを解析します。コードについては、上記のリテラルな名前パターンのみを照合します。
• 大文字の名前のみを追跡します。名前は [A-Z][A-Z0-9_]* に一致する必要があります。process.env の後に続く小文字で始まる名前は無視されます。小文字で始まる大文字・小文字混在の名前は追跡されません。
• 動的な環境変数へのアクセスは追跡できません。process.env[someVar]、process.env[prefix + suffix]、os.environ[some_var] のように、実行時に変数名を計算するコードでは、ソース内にリテラルな変数名がないため報告されません。動的キーは別途監査してください。
• 認識されるのは、リストに記載されたアクセス形式のみです。分割代入（const { FOO } = process.env）、os.environ.NAME の属性アクセス、フレームワークのヘルパーなど、その他の形式はこのバージョンでは検出されません。
• スキャン対象は .ts、.js、.mjs、.cjs、.py ファイルのみです。その他のファイル形式は無視されます。
• サンプルファイルは、対象ルートにある .env.example、次に .env.sample のみを検索します。ネストされたサンプルファイルは統合されません。
• 静的解析のみを行います。スキャン対象のリポジトリ内のコードは実行されません。

開発

npm install
npm run build
npm test

ライセンス

MIT