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.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 .

命令行界面

# 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

退出代码：

• 0：判定结果为 IN-SYNC
• 1：判定结果为 DRIFT
• 2：用法错误
• 141：读取方提前关闭了输出管道（在 shell 中显示为 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	中	代码中使用了某个变量，但示例文件中未列出。发现项会标明首次使用该变量的文件和行号。每个变量对应一条发现项。
DOCUMENTED-NOT-USED	低	示例文件中列出了某个变量，但代码中从未使用。始终允许列表中的变量除外。每个变量对应一条发现项。
NO-EXAMPLE	高	未找到 .env.example 或 .env.sample，但代码至少使用了一个变量。每份报告对应一条发现项。
VALUES-IGNORED	信息	报告中绝不会读取变量值。只解析名称；对于示例文件，只读取 = 左侧的内容。每份报告恰好有一条发现项。

每份报告中的计数：

• used：在代码中找到的不同变量数量
• documented：示例文件中列出的不同变量数量
• missing：已使用但未记录的变量数量（即 USED-NOT-DOCUMENTED 发现项的数量）
• stale：已记录但从未使用，且不在始终允许列表中的变量数量（即 DOCUMENTED-NOT-USED 发现项的数量）

始终允许列表

即使仓库中的代码没有读取，这些变量也绝不会被标记为 documented-not-used。它们通常由平台、运行时或 CI 设置，而非由应用代码设置：

• NODE_ENV
• PORT
• HOST
• CI
• DEBUG

此列表仅适用于 DOCUMENTED-NOT-USED 规则。如果代码使用了其中某个变量但未记录，该变量仍会像其他变量一样被报告为 USED-NOT-DOCUMENTED。

判定规则

• IN-SYNC：没有中或高严重性发现项。仍可能存在低严重性和信息级发现项。退出代码为 0。
• DRIFT：至少存在一条中或高严重性发现项。退出代码为 1。

特殊情况：如果不存在示例文件，且代码完全没有使用变量，则判定结果为 IN-SYNC，所有发现项的严重性均为信息级，摘要为 "no env usage found"。

如果不存在示例文件，但代码确实使用了变量，则判定结果为 DRIFT，并包含一条高严重性的 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