npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@code-pushup/ci

v0.54.0

Published

CI automation logic for Code PushUp (provider-agnostic)

Downloads

241

Readme

@code-pushup/ci

npm downloads dependencies

🔎🔬 Quality metrics for your software project. 📉🔍

  1. ⚙️ Configure what you want to track using your favourite tools.
  2. 🤖 Integrate it in your CI.
  3. 🌈 Visualize reports in a beautiful dashboard.

This package exports provider-agnostic core logic for running Code PushUp in CI pipelines. It serves as the base for the following provider integrations:

| | | | :------------- | :-------------------------------------------------------------------------------------------------- | | GitHub Actions | code-pushup/github-action | | GitLab CI/CD | code-pushup/gitlab-pipelines-template |

Setup

npm install @code-pushup/ci
yarn add @code-pushup/ci
pnpm add @code-pushup/ci

Usage

The runInCI function implements the full CI flow:

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

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

Parameters

Git refs

For each CI run, you must pass in the commit SHA and Git ref (e.g. main) of what was pushed. These values can be detected from the CI environment, the details depend on which provider is being used.

If only the head is supplied, then Code PushUp will collect a new report and optionally upload it to portal (depending on your Code PushUp config). If triggered by a pull request, then specify the base ref as well. This will additionally compare reports from both source and target branches and post a comment to the PR.

| Property | Required | Type | Description | | :------- | :------: | :----------------------------- | :-------------------- | | head | yes | { ref: string, sha: string } | Current branch/commit | | base | no | { ref: string, sha: string } | Branch targeted by PR |

Provider API client

The PR flow requires interacting with the Git provider's API to post a comparison comment. Wrap these requests in functions and pass them in as an object which configures the provider.

| Property | Required | Type | Description | | :----------------------- | :------: | :----------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- | | createComment | yes | (body: string) => Promise<Comment> | Posts a new comment to PR | | updateComment | yes | (id: number, body: string) => Promise<Comment> | Updates existing PR comment | | listComments | yes | () => Promise<Comment[]> | Fetches all comments from PR | | maxCommentChars | yes | number | Character limit for comment body | | downloadReportArtifact | no | (project?: string) => Promise<string \| null> | Fetches previous (root/project) report.json for base branch and returns path, used as cache to speed up comparison |

A Comment object has the following required properties:

| Property | Type | Description | | :------- | :------- | :------------------------------------ | | id | number | Comment ID | | body | string | Content of comment as Markdown string | | url | string | Web link to comment in PR |

Options

Optionally, you can override default options for further customization:

| Property | Type | Default | Description | | :---------------- | :------------------------ | :------------------------------- | :-------------------------------------------------------------------------------- | | monorepo | boolean \| MonorepoTool | false | Enables monorepo mode | | projects | string[] \| null | null | Custom projects configuration for monorepo mode | | task | string | 'code-pushup' | Name of command to run Code PushUp per project in monorepo mode | | directory | string | process.cwd() | Directory in which Code PushUp CLI should run | | config | string \| null | null [^1] | Path to config file (--config option) | | silent | boolean | false | Toggles if logs from CLI commands are printed | | bin | string | 'npx --no-install code-pushup' | Command for executing Code PushUp CLI | | detectNewIssues | boolean | true | Toggles if new issues should be detected and returned in newIssues property | | logger | Logger | console | Logger for reporting progress and encountered problems |

[^1]: By default, the code-pushup.config file is autodetected as described in @code-pushup/cli docs.

The Logger object has the following required properties:

| Property | Type | Description | | :------- | :-------------------------- | :----------------- | | error | (message: string) => void | Prints error log | | warn | (message: string) => void | Prints warning log | | info | (message: string) => void | Prints info log | | debug | (message: string) => void | Prints debug log |

Standalone mode

By default, it is assumed that Code PushUp is set up to run on the whole repo with one command (standalone mode). If you want to run Code PushUp on multiple projects separately, you should enable monorepo mode.

Standalone result

In standalone mode, the resolved object will include paths to report files (JSON and Markdown formats), as well as diff files, comment ID and new issues in case of PR comparisons.

const result = await runInCI(refs, api);

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

Monorepo mode

For monorepo setups, Code PushUp reports can be collected and compared individually per project. All project comparisons are then combined into a single PR comment.

Use the monorepo option to activate monorepo mode:

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

The runInCI function will try to detect which monorepo tool you're using from the file system. The following tools are supported out of the box:

If you're using one of these tools, you can also skip auto-detection by setting monorepo option to 'nx', 'turbo', 'yarn', 'pnpm' or 'npm'.

If none of these tools are detected, then the fallback is to run Code PushUp in all folders which have a package.json file. If that's not what you want, then you can also configure folder patterns using the projects option (supports globs):

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

Based on which monorepo tool is used, Code PushUp CLI commands will be executed using a package.json script, Nx target, Turbo task, or binary executable (as fallback). By default, these are expected to be called code-pushup, but you can override the name using the task option:

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

Monorepo result

In monorepo mode, the resolved object includes the merged diff at the top-level, as well as a list of projects. Each project has its own report files and issues.

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
    diffArtifact,
  } = 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
      artifacts: { report, diff },
      // array of source code issues, can be used to annotate changed files in PR
      newIssues,
    } = project;
  }
}