Cookbook · Maintaining

Gate CI on graph health

Fail a pull request if the graph health score drops below a threshold. Two-file recipe: a script + a workflow.

Recipe

// scripts/upg-health.mjs
import { UPGClient } from '@unified-product-graph/sdk'

const upg = new UPGClient({ file: './product.upg' })
const { score, digest } = await upg.health()

console.log(JSON.stringify(digest, null, 2))

const THRESHOLD = 7
if (score < THRESHOLD) {
  console.error(`Graph health ${score}/10 below threshold ${THRESHOLD}`)
  process.exit(1)
}

What it does

health() returns a score (0–10) plus a structural digest of node + edge counts. Wire it into a CI step that exits non-zero on drop. Tune THRESHOLD to your team: start at 6, ratchet up as the graph matures.

Variations

GitHub Actions workflow

# .github/workflows/upg-health.yml
name: UPG Health
on: [pull_request]
jobs:
  health:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - run: node scripts/upg-health.mjs

Compare against base branch (delta gate)

// In CI: read main’s health from a previous artefact,
// fail only if score dropped ≥ 1 point vs base.

▶ Try in playground