@ code- pushup/ ci (英语)

🔎🔬 您的软件项目的质量衡量标准 . 📉🔍

1. ⚙️ 配置您想要使用您最喜欢的工具来跟踪的东西 .
2. 🤖 把它融入你的线人.
3. 🌈 在漂亮的仪表板上看到报告.

此套件导出 在 CI 管道中运行代码 PushUp 的提供者不可知核心逻辑它作为下列供应商一体化的基础:

设置

npm install @code-pushup/ci

yarn add @code-pushup/ci

pnpm add @code-pushup/ci

使用量

这个 runInCI 函数执行完整的 CI 流 :

import { runInCI } from '@code-pushup/ci';

const result = await runInCI(
  {
    /* Git refs */
  },
  {
    /* Provider API client */
  },
  {
    /* Options */
  },
);

参数

基调

对于每次CI跑步,你都必须通过承诺SHA和Git ref(例如:. main被推开的东西. 这些值可以从 CI 环境中检测出,细节取决于使用哪个提供者.

如果 head 提供,然后代码 PushUp 将收集新报告,并可选地将其上传到门户网站(取决于您的代码 PushUp 配置). 如果被拉动请求所触发,请指定 base 报告也一样. 这将进一步比较来源和目标部门的报告,并向公关发布评论.

API 客户端

PR流量需要与 Git 提供者的 API 互动发布比较注释. 将这些请求包成函数,并作为配置提供者的对象传送.

A 类 Comment 对象具有下列所需的属性:

选项

可选的,您可以覆盖默认选项以进一步定制 :

[^1]:默认 code-pushup.config 文件已自动检测到, 如描述的那样 @code-pushup/cli 文档。 。 。 .

[^2]: {task} 模式替换为 task 值,所以默认行为是使用 npx nx show projects --with-target=code-pushup --json编辑 nxProjectsFilter 选项使Nx用户能够灵活地以Nx CLI支持的替代方式过滤项目(例如. --affected, (中文(简体) ), --projects, (中文(简体) ), --exclude, (中文(简体) ), --type- 参考 nx 文档中的选项 详细情况.

独立模式

默认情况下,假设代码PushUp的设置是为了在全repo上运行一个命令(独立模式) (中文(简体) ). 如果您要在多个工程上单独运行代码 PushUp, 您应该启用 单相模式。 。 。 .

独立结果

在独立模式下,解析对象会包括报告文件的路径(JSON和Markdown格式),以及diff文件,注释ID和公关比较时的新问题.

const result = await runInCI(refs, api);

if (result.mode === 'standalone') {
  const {
    // output files, can be uploaded as job artifact
    files: { current, comparison },
    // ID of created/updated PR comment
    commentId,
    // array of source code issues, can be used to annotate changed files in PR
    newIssues,
  } = result;
}

Monorepo 模式

对于单重置设置,可以收集并比较代码 PushUp 报告 每个项目。 将所有项目比较合并为 单公关评论.

使用 monorepo 选项以激活单曲模式 :

await runInCI(refs, api, {
  monorepo: true,
});

这个 runInCI 函数将尝试从文件系统中检测您正在使用的哪一个单列波工具 . 框外支持以下工具:

• 无
• 涡轮
• Yarn 工作空间
• pnpm 工作空间
• npm 工作空间

如果使用其中一个工具,也可以通过设置跳过自动检测 monorepo 选项到 'nx', (中文(简体) ), 'turbo', (中文(简体) ), 'yarn', (中文(简体) ), 'pnpm' 或者说 'npm'。 。 。 .

如果没有检测到这些工具,那么后退就是运行代码 PushUp in 包含所有文件夹 package.json 文档。 如果这不是你想要的,那么 您也可以使用 projects 选项( 支持 globs ):

await runInCI(refs, api, {
  monorepo: true,
  projects: ['frontend', 'backend/*'],
});

基于使用 monrepo 工具, 代码 PushUp CLI 命令将被执行 使用一个 package.json 脚本、 Nx 目标、 Turbo 任务或二进制可执行文件( 如 倒计时). 默认情况下,它们将被调用 code-pushup不过你 能够使用 task 选项 :

await runInCI(refs, api, {
  monorepo: 'nx',
  task: 'analyze', // custom Nx target
});

并行任务

默认情况下,单列波中每个项目的任务按顺序运行. 这个 parallel 选项允许支持它的工具(Nx、Turborepo、PNPM、Yarn 2+)并行执行.

await runInCI(refs, api, {
  monorepo: true,
  parallel: true,
});

最多同时进行的任务数可以通过一个数字而不是布尔来设定 :

await runInCI(refs, api, {
  monorepo: true,
  parallel: 3,
});

单收结果

在单雷波模式下,已解析对象包括顶层被合并的diff,以及项目列表. 每个项目都有自己的报告文件和问题.

const result = await runInCI(refs, api);

if (result.mode === 'monorepo') {
  const {
    // array of objects with result for each project
    projects,
    // ID of created/updated PR comment
    commentId,
    // merged report-diff.md used in PR comment, can also be uploaded as job artifact
    files: { comparison },
  } = result;

  for (const project of projects) {
    const {
      // detected project name (from package.json, project.json or folder name)
      name,
      // output files, can be uploaded as job artifacts
      files: { current, comparison },
      // array of source code issues, can be used to annotate changed files in PR
      newIssues,
    } = project;
  }
}

高级用途

更快的 CI 运行方式 configPatterns

默认情况下 print-config 命令按顺序运行,以可靠地检测 code-pushup 配置 - 具体地说, 从何处读取输出文件( e)persist 配置)以及门户是否可以用作缓存(upload conf. 这样可以让每个项目都以自己的方式配置,而不会打破任何东西,但是可以让大块单放这些额外的 code-pushup print-config 处决可以累积并大大地减缓CI程序.

作为一个更可扩展的替代品, configPatterns 可以提供。 用户提前声明每个工程的配置方式, 允许 print-config 被跳过。 用户有责任确保每个项目都持有这种配置(不会被检查). 这个 configPatterns 支持字符串插入, 替换 {projectName} 与每个项目的(已粘结)名称相连接。 除此之外,每个项目 code-pushup.config 一定是完全一样 persist 财务报告和审定财务报表 upload 配置.

await runInCI(refs, api, {
  monorepo: true,
  configPatterns: {
    persist: {
      outputDir: '.code-pushup/{projectName}',
      filename: 'report',
      format: ['json', 'md'],
    },
    // optional: will use portal as cache when comparing reports in PRs
    upload: {
      server: 'https://api.code-pushup.example.com/graphql',
      apiKey: 'cp_...',
      organization: 'example',
      project: '{projectName}',
    },
  },
});

上份报告的最新搜索承诺

在比较报告时,可以缓存基础分支的报告. 如果一个项目有一个 upload 配置,然后询问端口 API 是否匹配此承诺的报告 。 如果未上载此类报告,则在CI文物中查阅该报告(由 downloadReportArtifact 内 ProviderApiClient) (中文(简体) ). 如无报告可查,则取出基分所并收取上报.

在某些情况下,可能没有关于主要部门最新承诺的报告,但最近其他一些承诺可能有一个有用的报告,例如如果 nxProjectsFilter 用于 --affected 旗帜。 在这种情况下 searchCommits 选项可以启用。 然后将检查主要分支最近承付的有限数目.

await runInCI(refs, api, {
  monorepo: 'nx',
  nxProjectsFilter: '--with-target=code-pushup --affected',
  // checks 10 most recent commits by default
  searchCommits: true,
  // optionally, number of searched commits may be extended up to 100
  // searchCommits: 30
});