vibator/vibator

# vibator [](https://github.com/vibator/vibator/actions/workflows/quality.yml) [](https://www.npmjs.com/package/vibator) [](https://nodejs.org) [](./LICENSE) vibator 是一个质量门禁引擎：一个用于可配置、基于 glob 作用域的规则的运行器。每一条发现都包含三个独立的字段（`message`、`expected`、`fix`）、其周围的源代码行，以及指向说明该标准的文档的路径。其输出旨在供人类直接阅读，并可由 CI 工具和编码 Agent 直接消费。 ## 为什么需要 Linter 检查语法，类型检查器检查类型。它们都无法捕捉在生成式和快速迭代的代码中常见的一类缺陷：无限增长的文件、仅添加到某一个语言环境（locale）中的翻译键、被读取但从未记录在案的 environment variable、从未重新生成的生成文件、仍在调用已废弃 API 的代码。 vibator 并不替代格式化工具、Linter、类型检查器或死代码工具。它涵盖了这些工具无法做到的检查。 ## 安装 ``` npm install --save-dev vibator pnpm add -D vibator yarn add -D vibator bun add -d vibator ``` 需要 Node 22 或更高版本。TypeScript 是一个可选的 peer dependency，仅基于 AST 的规则需要它；具有类型感知能力的规则会解析并使用项目自身的 TypeScript 安装。支持的版本为 5.4 到 6.x；目前尚不支持 TypeScript 7，因为其原生编译器未暴露规则所使用的 JS 编译器 API。 ## 用法 ``` npx vibator # run every enabled rule npx vibator --only max-lines # run one npx vibator --reporter json # machine-readable output npx vibator --staged # check only files staged for the next commit npx vibator --changed # check only uncommitted changes npx vibator --since origin/main # check only what this branch touched npx vibator list # every rule and its default severity npx vibator explain max-lines # the guideline behind a rule npx vibator init # write a starter vibator.json ``` 当报告任何严重级别为 error 的发现时，退出代码为 1。警告（Warning）不会导致运行失败。即使在某条规则失败后，每条规则也都会继续运行。 `--since origin/main` 是在存在违规项的代码库中引入 vibator 的推荐方式：新增的工作会立即被检查，旧文件会在下次被修改时受到检查，并且不需要 baseline 文件。 ## 配置说明 项目根目录下的 `vibator.json`。有关完整的参考，请参阅 [docs/configuration.md](./docs/configuration.md)；有关每条规则及其选项，请参阅 [docs/rule-catalog.md](./docs/rule-catalog.md)。 ``` { "$schema": "./node_modules/vibator/schema.json", "rules": { "no-conflict-markers": "error", "max-lines": [ { "include": ["src/**/*.{ts,tsx}"], "options": { "max": 400 } }, { "include": ["tests/**"], "options": { "max": 800 } } ], "env-example-sync": "warn", "locale-parity": "off" }, "guidelines": { "docs/code-style.md": ["max-lines", "meaningful-names"] } } ``` 每条规则都接受 `severity`（`error`、`warn` 或 `off`）、`include`、`exclude` 以及其自身的 `options`。单个字符串是 severity 的简写形式。block 数组会按每个 block 运行一次规则，这样代码库的不同区域就可以拥有不同的预算。配置中未出现的规则仍会以其默认 severity 运行。 `guidelines` 将您自己的文档映射到规则上，因此一项发现不仅指向规则自带的准则，也会指向您设定的标准。 ## 规则 | 规则 | 默认值 | 检查内容 | |------------------------|---------|-------------------------------------------------| | `no-conflict-markers` | error | 已提交的合并冲突标记 | | `max-file-size` | error | 因失误提交的超大文件 | | `max-lines` | error | 超过行数预算的文件 | | `banned-patterns` | off* | 特定于项目的被禁止的模式，使用纯 JSON 表示 | | `no-dead-doc-links` | error | 无法解析到任何内容的相对 Markdown 链接 | | `locale-parity` | off* | 源语言环境拥有但某些语言环境缺失的键 | | `env-example-sync` | warn | 读取但未记录在案的 Env vars，反之亦然 | | `tsdoc-coverage` | error | 缺失或不完整的 TSDoc | | `meaningful-names` | error | 占位符标识符（`data`、`res`、`tmp`） | | `prefer-array-methods` | warn | 可以使用 `map` 替代单语句循环 | | `no-deprecated-apis` | error | 对 `@deprecated` 声明的调用 | | `codegen-drift` | off* | 生成文件与其源文件不同步 | \* 在配置前为 off。这些规则需要特定于项目的选项（要禁止的模式、locales 目录、生成器命令）才能运行。 `vibator explain ` 会打印任何规则的完整准则。 `banned-patterns` 是添加项目特定检查的最快方式：每个条目都是一个正则表达式，并带有其自身的 `message`、`expected` 和 `fix`，在 JSON 中配置而无需编写 plugin。 ## 设计说明 - **无 baselines。** 没有 suppression 文件。可以通过 `// vibator-ignore: ` 豁免单行，并且必须提供原因。 为了逐步引入，可使用 `--changed` 或 `--since` 限定执行范围。 - **发现机制遵循 git。** 候选文件集即为 git 跟踪的文件加上它将保留的文件，因此会遵循 `.gitignore`，并且永远不会报告生成的输出。 - **共享分析。** 需要类型信息的规则在每个 tsconfig 中共享一个 TypeScript 程序。仅涉及语法的规则在每个文件中共享一个解析结果。 - **低依赖性。** Globbing 和终端颜色均来自 Node 本身。唯一的 runtime dependency 是 `zod`。 ## 编写您自己的规则 如果标准可以通过基于行的正则表达式来表达，请配置 `banned-patterns`，而不是编写代码。否则，规则就是一个普通对象，包含 `id`、准则、选项 schema、glob 默认值，以及 `checkFile`（针对每个文件）或 `check`（针对每个项目）： ``` // vibator-rules/no-direct-env-access.ts import { defineRule } from "vibator"; import { z } from "zod"; export default defineRule({ id: "no-direct-env-access", title: "Configuration is read through the config module", docs: "no-direct-env-access.md", scope: "file", defaultSeverity: "error", defaultInclude: ["src/**/*.ts"], defaultExclude: ["src/config/**"], optionsSchema: z.object({ module: z.string().default("src/config") }), checkFile({ file, bytes, options }) { const lines = bytes.toString("utf8").split("\n"); const index = lines.findIndex((line) => line.includes("process.env")); if (index === -1) return []; return [{ file, line: index + 1, message: "Reads process.env directly", expected: `Configuration comes from ${options.module}`, fix: `Add the value to ${options.module} and import it from there`, }]; }, }); ``` 像内置规则一样注册它： ``` { "plugins": ["./vibator-rules/no-direct-env-access.ts"], "rules": { "no-direct-env-access": "error" } } ``` `plugins` 接受仓库相对路径（在 Node 22.18+ 上包含 TypeScript）或包名，因此可以发布和共享 rule pack。有关完整的编写指南，请参阅 [docs/writing-rules.md](./docs/writing-rules.md)。 ## Agent 技能 该包为 Claude Code 及兼容的 Agent 提供了三项技能： - `configuring-vibator`：检查项目并编写合适的配置。 - `fixing-vibator-findings`：消费 JSON 报告并处理发现的问题。 - `writing-vibator-rules`：编写项目规则、其准则及测试。 ``` npx vibator skills --install # copy into .claude/skills/ npx vibator skills # list what is bundled ``` ## 准则 每条规则都在 `docs/rules/` 中附带了一份准则。这就是 `vibator explain ` 所打印的内容，也是各项发现所指向的目标。 要用您自己的文档替换规则的准则： ``` "max-lines": { "docs": "docs/our-file-length-policy.md" } ``` 要在不替换自带准则的情况下添加项目上下文： ``` "guidelines": { "docs/code-style.md": ["max-lines", "meaningful-names"] } ``` ## 文档 | 文档 | 涵盖内容 | |---------------------------------------------------|------------------------------------------------------| | [docs/configuration.md](./docs/configuration.md) | 配置格式、CLI、严重级别、globs、JSON 报告器 | | [docs/rule-catalog.md](./docs/rule-catalog.md) | 每条规则、其默认值和选项（自动生成） | | [docs/writing-rules.md](./docs/writing-rules.md) | 编写规则及发布 rule pack | | [docs/rules/](./docs/rules) | 每个内置规则一份准则 | ## 贡献 请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。参与受[行为准则](./CODE_OF_CONDUCT.md)约束。提交遵循 Conventional Commits；版本发布由 semantic-release 切割，并通过 OIDC trusted publishing 发布到 npm。 ## 许可证 [MIT](./LICENSE)

标签：GNU通用公共许可证, MITM代理, Node.js, SOC Prime, 云安全监控, 开发工具, 暗色界面, 自动化攻击, 静态分析