configdoc

configdoc

在一份文档中列出代码中的每个配置选项及其默认值。将源文件作为文本传给 configdoc，它会扫描文件，查找直接读取环境变量的代码——这是大多数代码库实际采用的配置方式——并返回一份清单：

• 两种读取形式 — 提取 process.env.NAME 和 import.meta.env.NAME，其中 NAME 符合大写环境变量命名约定（[A-Z_][A-Z0-9_]*）。不会匹配小写或大小写混合的名称；解构读取（const { X } = process.env）和非环境变量配置对象则按设计不在范围内。
• 默认值 — 如果读取后紧接着 ?? 或 || 和一个字面量，该字面量就是该读取的默认值：字符串字面量取引号之间的原始文本（不解析转义字符），数字字面量取其原样文本。如果回退值是标识符、调用或其他内容，则不会捕获默认值。
• 每个选项一条记录 — 每个不同的名称只出现一次，按升序排列；默认值取扫描顺序中该名称第一次捕获到默认值的读取（文件按输入顺序、行从上到下、匹配项从左到右）；如果没有读取捕获到默认值，则为 null。同时列出该名称在所有文件中的读取总次数，以及读取该名称的不同文件，按升序排列。

输入会经过严格验证：文件集缺失或为空、文件缺少 path 或 content、路径为空、不是字符串或重复，或者 content 不是字符串，都会报错并指出出错路径（例如 files[0].content must be a string），且不会生成不完整的清单。扫描完全在本地执行，不会访问网络、读取配置，也不会读取你所传输入之外的文件。

CLI

npx @reneturcios/configdoc extract --input args.json
npx @reneturcios/configdoc --version

args.json 包含完整的参数对象：

{
  "files": [
    {
      "path": "src/config.ts",
      "content": "const port = process.env.PORT ?? 8080;\nconst host = process.env.HOST ?? \"localhost\";"
    },
    {
      "path": "web/env.ts",
      "content": "export const api = import.meta.env.API_URL;"
    }
  ]
}

清单以 JSON 格式输出：

{
  "options": [
    { "name": "API_URL", "default": null, "reads": 1, "files": ["web/env.ts"] },
    { "name": "HOST", "default": "localhost", "reads": 1, "files": ["src/config.ts"] },
    { "name": "PORT", "default": "8080", "reads": 1, "files": ["src/config.ts"] }
  ],
  "total_options": 3,
  "files_scanned": 2
}

退出代码：成功时为 0，运行时错误（包括输入文件无法读取或无效，以及输入无效）时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/configdoc mcp

MCP 客户端配置：

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

工具

• extract_config_options — 提取代码中读取的每个配置选项，以及每次读取的回退默认值，并汇总为一份清单。
  • files（数组，必填，至少一个）— 源文件对象 {path, content}；集合中的 path 必须唯一，content 是完整的源文本（可以为空）

返回 {options, total_options, files_scanned}，其中每个选项为 {name, default, reads, files}。

Docker

docker run -i ghcr.io/cloudcorprecords/configdoc
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/configdoc extract --input /w/args.json

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

许可证

MIT — 版权所有 (c) 2026 Rene Turcios