@ codegeneai/ 质量

声明式,有计划驱动的质量管线(lint,格式,测试管线),用于单发和单发包——以Bun为主,用TypeScript书写.

bun add -D @codegeneai/quality
bun x quality init
bun x quality check

就是这样.. quality init 丢弃启动器 .qualityrc.jsonc 在你的回购,和 quality check 运行管道.

为什么会这样

大部分的回旋器都粘在一起了 husky, (中文(简体) ), lint-staged, (中文(简体) ), biome (或 eslint + 键 prettier),并用一叠活塞外壳脚本来强制实施犯罪前的质量以及CI. @codegeneai/quality 折叠成单一声明配置文件:管道、配置文件(local, (中文(简体) ), pre-commit, (中文(简体) ), pre-push, (中文(简体) ), ci),舞台适配器,钩子,和记者都住在 .qualityrc.jsonc。您在不写入类型Script的情况下进行检查,通过嵌入式配置在单列波包之间共享配置,并在本地和CI中运行相同的管道.

它与 Bun 和 Biome 特别配对,但是在阶段级别上都不需要——任何可以表示为命令的检查,或者作为相位适配器执行的检查.

核心概念

• 相位适配器 - 执行单一责任的单元(进口卫生、文件名、结构、包子、指挥等)。 适配器暴露出元数据(标签,描述,被支持的模式)和执行钩.
• 预设 - 命名了每个适配器定义的选项捆绑 stages.<adapter>.presets. 预设可以扩展其他预设(单一或多位继承)并配置默认,如组,模式,钩和适配器选项等.
• 简介 ——命名管线,可订购分级,设置记者,并附钩. 剖面可以相通相通,允许"局部"和"ci"变体有小diff.
• 组 – 阶段可以加入一个组来选择并行执行,失败快语义,或共享元数据.
• 钩子记者( R) – 声明外壳命令在起跑/成功/失败时运行,而记者(摘要/json/junit/动词)消耗了管道结果.
• 司马一等 – 一个被捆绑的JSON Schema模型整个配置表面,这样编辑器和CI就可以验证配置.

开始

1. 安装 : bun add -D @codegeneai/quality。 。 。 .
2. 安装后运行 bun x quality init 创建启动器 .qualityrc.jsonc (堆栈显示预设、命令阶段和分组适配器).
3. 参考里面的图谋 .qualityrc 启用编辑器 IntelliSense 的文件 :

{
  "$schema": "./node_modules/@codegeneai/quality/schemas/qualityrc.schema.json",
  "stages": {
    "command": {
      "presets": {
        "docs:check": {
          "continueOnError": true,
          "options": {
            "abortPipelineOnFailure": false,
            "commands": ["bun run docs:lint"]
          }
        }
      }
    }
  }
}

支持的编辑器 npm: schema 引用( 或您的 monorepo 工具) 也可以使用 "$schema": "npm:@codegeneai/quality/schemas/qualityrc.schema.json"相对 ./node_modules/... 上面的路到处都行.

配置文件可以完全生活在硬文件(例如, .qualityrc.local.jsonc, (中文(简体) ), .qualityrc.pre-push.jsonc) (中文(简体) ). 如果基础配置省略了配置文件,加载器会自动发现shards并默认为 local (或 a 个) --profile 覆盖 / 第一个找到的硬度 .

创建额外 .qualityrc 用于该子树的扩展/覆盖阶段。 装入器从被嵌入的文件向上走去,合并了预设,剖面图,钩子,以及适配器注册.

碎片和剖面图

• 基础配置 : .qualityrc.jsonc (或 .json) (中文(简体) ).
• 剖面板块 : .qualityrc.<profile>.jsonc|json 自动加载并在基座上方合并。 默认 shards 生活在基数配置旁; set "shardDir": "relative/path" 在基础配置中从另一个目录中装入硬块.
• 示例软体: .qualityrc.local-fast.jsonc, (中文(简体) ), .qualityrc.pre-commit.jsonc, (中文(简体) ), .qualityrc.pre-push.jsonc, (中文(简体) ), .qualityrc.ci.jsonc。 。 。 .

配置参考

文件与碎片

• 基础配置 : .qualityrc.jsonc (或 .json. JSON/JSONC仅限.
• 剖面板块 : .qualityrc.<profile>.jsonc|json 自动加载并合并在基座上方. 默认位置与基准相同; 设置 "shardDir": "relative/path" 在基础配置中从自定义文件夹中装入硬块.
• 示例软体: .qualityrc.local-fast.jsonc, (中文(简体) ), .qualityrc.pre-commit.jsonc, (中文(简体) ), .qualityrc.pre-push.jsonc, (中文(简体) ), .qualityrc.ci.jsonc。 。 。 .

自动修正默认

• 每个配置文件接受 autoFix: true 在核查前运行可修复的阶段而不通过 --auto-fix。 。 。 .
• 开发者可以在给定引用时禁用默认 --no-auto-fix。 。 。 .
• 使用 -a 化名可以使钩和脚本保持简短,同时可以明确地自动固定.
• 实例配置配置和使用:

{
  "profiles": {
    "local": {
      "pipeline": [
        { "id": "lint:imports", "type": "imports" },
        { "id": "lint:structure", "type": "structure" }
      ],
      "autoFix": true // Enable auto-fix by default
    }
  }
}

quality check  # Auto-fix enabled (profile default)
quality check --no-auto-fix  # Override to disable auto-fix
quality check -a  # Explicitly enable auto-fix regardless of profile default

CLI 参考(质量)

• quality check [-a|--auto-fix] [--no-auto-fix] [--profile <name>] [--files <glob>] [--stage <id>] [--reporter <name>] [--json <path>] [--shard-dir <dir>]
• quality run --stage <id> [--mode check|fix|report] [--shard-dir <dir>]
• quality list [--adapters] [--shard-dir <dir>]
• quality init
• quality validate-config [--stage <id>] [--shard-dir <dir>] (打印已解析的配置/阶段为JSON)
• quality config validate [--shard-dir <dir>] (验证所有配置/硬度)
• quality config print [--compact] [--shard-dir <dir>] (打印合并了配置;默认的漂亮打印,使用) --compact 用于单行JSON)
• quality telemetry analyze [--file <path>] [--profile <name>] [--context <substring>] [--success-only] [--json]

分辨率命令 : CLI 旗帜(--auto-fix 或者说 --no-auto-fix• 概况 autoFix → false (默认).

全局忽略

• 设定 ignore 位于根基处 .qualityrc 以提供应当 被跳过每个阶段。 这些模式增加了内置默认值 (单位:千美元)node_modules, (中文(简体) ), .git,缓存等)并流经适配器内部,故作: 单项,例如 "scripts/helpers/**" 将帮助目录从内出, 钩子 和舞台上特有的光彩.

内置适配器

• 导入 – 每个允许列表的脱去文件扩展名 .
• 包-内生-警卫 node: 进口.
• 文件名 — 执行测试/ 固定命名 .
• 结构——需要文件存在/缺失;支持 requireWithContent (自动固定创建/覆盖)例如, CLAUDE.md 与 @./AGENTS.md。 。 。 .
• 单位-高级——确保单位测试(例如, *.unit.spec.ts)坐在主题文件旁边. 仅允许在下列条件下进行无试验: src/__tests__/ (可配置),并且只有在该文件夹仅包含单元测试; requireSubject 和目录选项可配置.
• 命令 —— 运行任意命令.
• 软件包标记 — 执行所需的脚本 package.json 文档.
• 软件包目录 — 强制使用依赖性版本 catalog:<name> (或 workspace:),可选的用根目录图重写固定模式.
• 枪管出口——执行枪管档案公约.
• biome-config ——验证 Biome 配置一致性.
• biome-ignore——保持Biome忽略列表同步.
• changet-guard – 在所配置的分支上守护更动的用法.
• dockerfile- required – 需要在所选包中需要多克file.
• dotenv- plaintext — 旗下正文机密 .env 文档.
• dotenv-secrets——验证dotenvx加密的秘密文件.

支持部分文件输入荣誉的适配器 --files 和概况级别 filesMode 选择。 在承诺前的简介中, biome-ignore, (中文(简体) ), dotenv-plaintext,以及 dotenv-secrets 只检查匹配的已完成的文件和 当不相关的文件被设置时快速跳过, 而工作空间/ CI 配置文件仍然 进行他们配置的全扫描.

软件包目录

确保目标版本的依赖性 package.json 文件使用共享目录( Bun monorepo 特性; 在单包重置中可以安全跳过) .

选项 :

• packages (字符串 []): glob(s) 到 package.json 文件(已忽略: **/node_modules/**) (中文(简体) ).
• sections (字符串[]):需要扫描的依赖区块;默认为 dependencies, (中文(简体) ), devDependencies, (中文(简体) ), peerDependencies。 。 。 .
• allowlist (字符串[]):包名(globs)为免名.
• rootCatalogPath (字符串):根包文件的路径,包含 catalogs (默认 : package.json) (中文(简体) ).

行为 :

• 检查: 如果缺少目标依赖, 则失败 catalog:<name> 或者说 workspace:*。当目录条目存在时,信件指向预期条目 catalog:<name>;否则它要求将 dep 添加到根目录或允许列表中.
• 修补: 将符合条件的道口重写为 catalog:<name> 当根目录条目存在时。 没有目录条目的 Deps 仍然在引导下失败.

示例阶段:

{
  "id": "package-catalog",
  "type": "package-catalog",
  "overrides": {
    "packages": [
      "packages/*/package.json",
      "packages/*/*/package.json",
      "packages/*/*/*/package.json",
      "services/*/package.json",
      "apps/*/package.json",
      "!packages/example/stacks/**/package.json"
    ],
    "allowlist": ["@your-scope/*"]
  }
}

胡斯基钩 (推荐品)

使用Husky连接 Git 钩子与您的质量配置 。 也可以使 Git LFS 快乐的示例钩 :

.husky/pre-commit

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"
command -v git-lfs >/dev/null 2>&1 && git lfs pre-commit "$@"
bun x quality check --profile pre-commit --files-mode staged --reporter summary

.husky/pre-push

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"
command -v git-lfs >/dev/null 2>&1 && git lfs pre-push "$@"
bun x quality check --profile pre-push --files-mode workspace --reporter summary

设置步骤 :

1. bun add -D husky。 。 。 .
2. 添加 "prepare": "husky install" 改为 package.json 因此新安装创建 .husky/。 。 。 .
3. 提交 .husky/* 钩入文件与您的 .qualityrc 简介.

定义专用配置(例如, pre-commit, (中文(简体) ), pre-push(单位:千美元) .qualityrc 所以钩子命令保持稳定。 胡斯基住在这里 .husky/ (通过) core.hooksPath),避免与Git LFS和其他工具相冲突.

阶段规格

每个阶段的条目都决定 ResolvedStage 与这些领域:

已声明的文件名 files 在运行时同步解析并缓存到每个模式/root/ignore组合,这样共享模式的组不会重复相同的文件系统扫描.

有条件的语法

• 通过 env.VAR_NAME 或多点密钥( e)env.NODE_ENV) (中文(简体) ).
• 支持的运算符 : !, (中文(简体) ), &&, (中文(简体) ), ||, (中文(简体) ), ===, (中文(简体) ), !==, (中文(简体) ), ==, (中文(简体) ), !=, (中文(简体) ), <, (中文(简体) ), <=, (中文(简体) ), >, (中文(简体) ), >=。 。 。 . ==编号 :!= 对内存提供的字符串进行有限的强制(例如, "true" → true,数字字符串 = 数字),让传统卫士继续工作.
• 支持的字节:字符串(单引出或双引出),数字, true编号 :false, (中文(简体) ), null, (中文(简体) ), undefined。 。 。 .
• 括号允许分组;未匹配的括号或未知的符号会使条件失效并跳过舞台.
• 优先进行简短、明确的检查,例如: env.NODE_ENV === "ci" 或者说 env.QUALITY_FLAG === "1"; 避免隐藏失败模式的链式逻辑( )(env.A === "1" && env.B === "1") || env.C === "1") (中文(简体) ).
• 条件解决缺失的环境变量 undefined; 明确包括默认(例如, env.TARGET ?? "local" === "ci" 不支持, 使用 env.TARGET === "ci") (中文(简体) ).
• 将字符串字符串在引文中包入并避免插入路径或 shell 表达式. 所有未知的符号都会使该条件被评估到 false 所以舞台被跳过.
• 在预设中捕获普通护栏(例如a) ci-only 预设设置 if: "env.CI === \"true\""保持各服务部门的舞台规格一致.
• 添加新配置文件以减少无效时与配置作者共享此指导 if 表达式; 将条件缩短、引用和明确.

组和并行执行

• 同一组内的相位 ID 当 parallel: true。 。 。 .
• failFast: true (默认)在第一次失败时中止兄妹阶段 AbortController。 。 。 .
• continueOnError: true 在舞台或组合上允许管道在故障后继续运行.
• 无论平行执行,跑者都按决定顺序汇总产出.
• 按组别计算 profiles.<name>.parallelLimit (首选)或 QUALITY_PARALLEL_LIMIT。设定时,配置值将胜出.

阶段计时遥测

• 设定 QUALITY_TELEMETRY=stdout (或 file发送包含已解决的元数据 parallelLimit源代码和a stageTiming 摘要(管道持续时间、综合阶段时间、最长阶段和每阶段使用分组编号的时间).
• 比较 stageTiming 字段横跨不同 parallelLimit 值来理解在受限主机上的争议; 差异很大 serialDurationMs 财务报告和审定财务报表 pipelineDurationMs 表明有效的平行主义.
• 使用元数据验证低功率配置文件:保持相同的相位顺序和结果,同时监测收紧的封顶是否缩短了墙钟持续时间或稳定了CI吞吐.

分析遥测输出

• 运行 quality telemetry analyze --file <path> (违约) ./quality-telemetry.log)总结阶段时间 parallelLimit 及其来源。 添加 --profile <name> 或者说 --context <substring> 专注于具体的运行, --success-only 排除失败,以及 --json 用于机器可读输出.
• 检查 parallel ratio 栏(pipelineDurationMs / serialDurationMs),用来衡量您在每个极限中获得多少并行性. 数值较低表明重叠情况较好(例如:, 0.5x 击出 1.0x),这纯粹是连环行刑.
• 调试时抓取并比较低功率主机的摘要 parallelLimit:如果收紧的上限能提高效率而不会降低成功率,则更倾向于该特征的更小的上限.

命令适配器选项

command 阶段接受:

适配器收集每个指令的stdout/stderr,尊重管道中止信号,并以结构化细节报告超时.

何时 output 被配置适配器流 stdout/stderr 通过 命令输出过滤器, 只释放被过滤的行( 例如, 失败) 包:测试断言). 通过阶段可以完全通过设置来压制日志 showOnSuccess: "none",保留 quality check 输出紧密,即使 基础命令很吵 设定 QUALITY_SHOW_ALL_OUTPUT=1 或通过 --show-command-output 到 CLI 以绕过特定运行的过滤.

扩展适配器

通过导出返回 a 的模块添加自定义适配器 StageAdapter数字 :

// tools/quality/custom-adapter.ts
import type { StageAdapter } from "@codegeneai/quality";

export const greetAdapter: StageAdapter<{ message?: string }> = {
  type: "greet",
  label: "Greeter",
  description: "Prints a greeting",
  async run(context) {
    const message = context.options.message ?? "hello";
    console.log(message);
    return { status: "passed" };
  },
};

export default { adapters: [greetAdapter] };

引用模块路径从 .qualityrc数字 :

{
  "$schema": "./node_modules/@codegeneai/quality/schemas/qualityrc.schema.json",
  "adapters": ["./tools/quality/custom-adapter.ts"],
  "profiles": {
    "local": {
      "pipeline": [
        { "id": "greet", "type": "greet", "overrides": { "message": "hi" } }
      ]
    }
  }
}

加载器会解析相对于配置文件的模块路径,注册适配器,并将预设的元数据曝光到CLI.

Schema 验证( A)

捆绑的JSON Schema(@codegeneai/quality/schemas/qualityrc.schema.json说明:

• 根键( R)$schema, (中文(简体) ), adapters, (中文(简体) ), stages, (中文(简体) ), profiles, (中文(简体) ), reporters, (中文(简体) ), hooks) (中文(简体) ).
• 内置适配器选项 specs(进口/bun-native/filenames/架构/无根-管/命令).
• 组元数据,并行语义,和钩子谱.

单位测试使用供应商JSON Schema验证器确保样本 .qualityrc 文档仍然遵守。 相对计划路径的点编辑器( E)./node_modules/@codegeneai/quality/schemas/qualityrc.schema.json) 或主机设计 $id 全球分布.

CLI 参考

Usage: quality <command> [options]

Commands:
  quality check [-a|--auto-fix] [--no-auto-fix] [--profile <name>] [--files <glob>] [--stage <id>] [--reporter <name>] [--json <path>]
  quality run --stage <id> [--mode check|fix|report] [--files <glob>]
  quality list [--adapters]
  quality validate-config [--profile <name>] [--stage <id>]
  quality config validate [--shard-dir <dir>]
  quality config print [--compact]
  quality init [--cwd <path>]
  quality telemetry analyze [--file <path>] [--profile <name>] [--context <substring>] [--success-only] [--json]

要点 :

• quality list 打印已解析的管道. quality list --adapters 显示已注册的适配器、支持的模式和预设描述.
• -a 编号 : --auto-fix 在核查前运行可修复的阶段(使用 --no-auto-fix 要禁用); 设置 autoFix: true 用于默认此行为的配置文件.
• quality validate-config 通过 --stage。 。 。 .
• quality run --stage 执行单个相控相(用于命令适配器或调试).
• --reporter 可重复; --json <path> 自动添加 JSON 记者 .
• 使用 Husky 将 git hooks 连接到您定义的配置文件( 见上文 Husky 部分); 质量 CLI 不管理 .git/hooks 直接说.

内嵌配置

额外位置 .qualityrc 用于自定义该子树的预设或附加阶段。 加载器在此顺序下合并配置 :

1. 仓库根 .qualityrc。 。 。 .
2. 组合继承( E)extends) (中文(简体) ).
3. 嵌入 .qualityrc 离目标文件最近的文件.
4. 阶段级控制器.

在嵌入式配置中声明的适配器自动注册.

发展

git clone https://github.com/CodeGeneAI/quality.git
cd quality
bun install
bun run test:unit

• 类型检查 : bun run typecheck
• 林特: bun run lint
• 单位测试 : bun run test:unit
• 避免 bun test,它是一个意外的范围。 总是执行 bun run test:unit 为了可靠的结果.

试验与源并存(例如, src/pipeline/runner.unit.test.ts) (中文(简体) ). 下接缝 test/fixtures/** 锻炼加载器行为,预设继承,以及计划验证.

运行 quality check 在发布更改之前,确保记者、钩子和适配器保持功能.

捐款

欢迎捐款——见 CONTRIBUTING.md 如何增加一个新的舞台适应器。 安全问题应通过下列方式私下报告: GitHub 安全顾问 看到了吗 SECURITY.md。 。 。 .

许可证

麻省理工学院 代码GeneAI