delivery-intel

v1.7.0

Published

a month ago

Evidence-driven repo intelligence: DORA metrics, forensic signals, vulnerability scan, and delivery verdict for any GitHub repo. One command, no setup.

delivery-intel

Evidence-driven repo intelligence for any GitHub repo.

The fastest way to determine whether a repo is safe to adopt, healthy to change, and disciplined enough to trust in CI.

delivery-intel answers three questions — with evidence, not guesses:
Does this repo ship well? (deployment frequency, lead time, forensic signals)
Does it fail safely? (change fail rate, recovery time, vulnerabilities, flaky pipelines)
Is it getting better or worse? (30-day trend, verdict: exemplary / fast-but-fragile / unstable)
Every metric shows its source, sample size, and confidence level. No fake precision.

⚡ Quick Start

# Verdict mode — grade, confidence, forensics, policy (v2 engine)
npx delivery-intel facebook/react --v2

# Mode-specific analysis (implies --v2)
npx delivery-intel facebook/react --mode adopt

# Classic metrics dump (v1 engine)
npx delivery-intel facebook/react

┌──────────────────────────────────────────────────────────────┐
│  facebook/react                                              │
│  Grade A-   Score 91/100   Confidence high                  │
│  Trend ↑ +4 pts                                             │
└──────────────────────────────────────────────────────────────┘

✓   NO POLICY VIOLATIONS
──────────────────────────────────────────────────────────────
  ✓ All delivery health policies are passing.

METRICS  (source · sample · confidence)
──────────────────────────────────────────────────────────────
  ◆ Deploy Frequency       12.4/wk  [high]  deployment_statuses
  ◆ Change Lead Time       3.2h     [high]  commit_to_deploy (84 PRs)
  ● Recovery Time          0.8h     [med]   deployment_failures
  ◆ Change Fail Rate       4.8%     [high]  deployment_statuses
  ● Pipeline Failures      8.2%     [high]  workflow_runs (52 runs)

SIGNAL QUALITY
──────────────────────────────────────────────────────────────
  ◈ Production signal strength: high
  ✓ Scanned manifests: npm (package.json), Go (go.mod)

SECURITY
──────────────────────────────────────────────────────────────
  ✓ No known vulnerabilities found in scanned manifests

Works with full URLs too: npx delivery-intel https://github.com/vercel/next.js --v2

Why DORA metrics matter

Google's 2024 DORA Report (32,000+ respondents, 10 years of data):

| Metric | Elite teams | Low performers | Gap | |--------|------------|----------------|-----| | Deploy Frequency | On-demand (multiple/day) | < once per 6 months | 973× | | Lead Time for Changes | < 1 hour | 1 – 6 months | 6,570× | | Change Failure Rate | 0–15% | 46–60% | — | | Time to Restore | < 1 hour | 1 week – 1 month | 6,570× |

Elite teams are 2× more likely to meet reliability targets and 1.8× more likely to meet business goals (DORA 2024).

Lead Time ★ Elite 3.2 hours median (0.1 days)

Change Failure Rate ● High 4.8% (2 failed / 42 total runs)

◈ Vulnerability Scan (OSV.dev) ──────────────────────────────────────────────────────── ✓ No known vulnerabilities found

◈ Suggestions ──────────────────────────────────────────────────────── ✓ Looking good, no critical issues detected


> Works with full URLs too: `npx delivery-intel https://github.com/vercel/next.js`

---

## What It Measures

| Metric | What it tells you | Source | Confidence |
|--------|-------------------|--------|------------|
| **Deploy Frequency** | How often code ships to production | Deployment statuses → deploys → Actions → PRs | Waterfall |
| **Change Lead Time** | Commit → production (PR flow as fallback) | Deployments + commits | High / Low |
| **Change Fail Rate** | % of deployments that failed or rolled back | Deployment statuses + heuristics | High / Low |
| **Recovery Time** | Time from failure to successful recovery | Deployment failures + workflow runs | High / Low |
| **Pipeline Failure Rate** | CI workflow run reliability (distinct from CFR) | Workflow Runs API | High |
| **Deployment Rework Rate** | Rollback/revert/hotfix rate (inferred) | PR titles + labels + deployment refs | Low (flagged) |
| **Vulnerabilities** | Known CVEs across 7 manifest ecosystems | [OSV.dev](https://osv.dev) batch API | — |
| **Delivery Score** | Confidence-weighted composite (0–100) | All of the above | Aggregate |

> Every metric exposes: data source · sample size · lookback window · confidence level.
> Low-confidence signals contribute less to the composite score — no fake precision.

Supported manifest ecosystems: **npm** · **pip** · **Go modules** · **Poetry** · **pnpm** · **Cargo** · **RubyGems**

---

## Usage

### CLI (zero install)

```bash
# Verdict: grade, confidence, policy violations, evidence chain (v2 engine)
npx delivery-intel facebook/react --v2

# Classic metrics output (v1 engine — backwards compatible)
npx delivery-intel facebook/react

# Compare last 30 days vs prior 30 days
npx delivery-intel vercel/next.js --trend

# Include workflow strain analysis
npx delivery-intel vercel/next.js --risk

# AI-powered executive narrative (requires LLM key — falls back to template)
npx delivery-intel vercel/next.js --narrative

# JSON output (v2 includes full evidence chain + policy result)
npx delivery-intel vercel/next.js --v2 --json

# Save report to file
npx delivery-intel vercel/next.js --v2 --json --output report.json

All flags

| Flag | Description | |------|-------------| | --v2 | Evidence-driven engine with grade, confidence, forensics, and policy | | --mode <mode> | Analysis mode: oss, adopt, pr, exec, platform (implies --v2) | | --pr-comment | Write a PR guardrail comment to delivery-intel-pr-comment.md (use with --v2) | | --fail-below N | Exit code 2 if delivery score is below N | | --block | Enable blocking violations (use with --v2 --fail-below) | | --json | Output raw JSON instead of the formatted terminal report | | --output <file> | Write JSON to a file (can combine with --json) | | --trend | Show 30-day vs prior-30-day deltas for all metrics | | --risk | Include workflow strain analysis (velocity + stability signal) | | --narrative | Generate an executive summary (LLM or template fallback) | | --token <token> | GitHub token — prefer gh auth login instead | | --no-spinner | Disable the scanning animation (useful in CI logs) | | --version | Print version | | --help | Show help |

Web Dashboard

git clone https://github.com/ParthibanRajasekaran/delivery-intel.git
cd delivery-intel
npm install
npm run dev
# → http://localhost:3000

Paste a repo URL and get an animated dashboard with score ring, DORA cards, charts, vulnerability table, and suggestions.

Docker

# Dashboard
docker compose up dashboard

# CLI
REPO=facebook/react docker compose run --rm cli

📦 JSON Output Schema

Pass --json (or --json --output report.json) to get machine-readable output.

{
  "repo": { "owner": "vercel", "repo": "next.js" },
  "fetchedAt": "2026-04-17T12:00:00.000Z",
  "overallScore": 87,                          // 0–100
  "doraMetrics": {
    "deploymentFrequency": {
      "deploymentsPerWeek": 12.4,
      "rating": "Elite",                       // Elite | High | Medium | Low
      "source": "merged_prs_fallback"          // deployments_api | merged_prs_fallback
    },
    "leadTimeForChanges": {
      "medianHours": 3.2,
      "rating": "Elite"
    },
    "changeFailureRate": {
      "percentage": 4.8,
      "failedRuns": 2,
      "totalRuns": 42,
      "rating": "High"
    }
  },
  "vulnerabilities": [
    {
      "packageName": "lodash",
      "currentVersion": "4.17.15",
      "vulnId": "GHSA-xxxx-xxxx-xxxx",
      "summary": "Prototype pollution",
      "severity": "high",                      // critical | high | medium | low
      "aliases": ["CVE-2021-23337"],
      "fixedVersion": "4.17.21"
    }
  ],
  "suggestions": [
    {
      "category": "reliability",               // performance | reliability | security
      "severity": "high",                      // high | medium | low
      "title": "High Pipeline Failure Rate",
      "description": "...",
      "actionItems": ["..."]
    }
  ],
  "dailyDeployments": [0, 1, 2, 3, 1, 2, 3], // last 7 days, index 0 = 6 days ago
  // present only with --trend
  "trend": {
    "windowDays": 30,
    "current":  { "deploymentsPerWeek": 12.4, "leadTimeHours": 3.2, "changeFailureRate": 4.8, "score": 87 },
    "prior":    { "deploymentsPerWeek": 9.1,  "leadTimeHours": 5.6, "changeFailureRate": 6.2, "score": 78 },
    "deltas":   { "deploymentsPerWeek": 3.3,  "leadTimeHours": -2.4, "changeFailureRate": -1.4, "score": 9 }
  },
  // present only with --risk
  "riskScore": {
    "score": 42,
    "level": "moderate",                       // low | moderate | high | critical
    "cycleTimeDelta": 0.12,
    "failureRateDelta": -0.05,
    "sentimentMultiplier": 1.0,
    "summary": "..."
  }
}

🔐 Authentication

| Method | Setup | Best for | |--------|-------|----------| | None | Just run it | Public repos (60 req/hr) | | gh auth login | brew install gh && gh auth login | Daily use, token stays in OS keychain ✨ | | GITHUB_TOKEN | export GITHUB_TOKEN=ghp_... | CI environments | | --token | --token ghp_... | Quick one-off (avoid in CI) |

Token resolution order: --token flag → GITHUB_TOKEN env → gh auth token

Private repos require a token with repo scope. For CI, use ${{ secrets.GITHUB_TOKEN }}. It's auto-scoped and expires per job.

CI Integration

GitHub Actions Marketplace action

The easiest way — use the action directly:

# .github/workflows/delivery-intel.yml
name: Delivery Health Check

on:
  push:
    branches: [main]
  pull_request:

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: ParthibanRajasekaran/[email protected]
        with:
          fail-below: '40'   # fail the job if score drops below 40

Outputs available after the step: score, deploy-frequency, lead-time, change-failure-rate, mean-time-to-restore.

Evidence-backed PR guardrail (v2 engine)

Posts a policy-aware comment on every PR — no block unless a real threshold is breached:

    steps:
      - name: Delivery Health Check
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          npx delivery-intel@latest ${{ github.repository }} \
            --v2 \
            --pr-comment \
            --fail-below 40 \
            --no-spinner

      - name: Post PR Comment
        if: always() && github.event_name == 'pull_request'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh pr comment ${{ github.event.pull_request.number }} \
            --body-file delivery-intel-pr-comment.md \
            --repo ${{ github.repository }}

The comment leads with a verdict (✅ No block / ⚠️ Warning / 🚫 BLOCKED), followed by a collapsible metrics table with source and confidence for every data point.

npx (custom pipeline)

    steps:
      - name: Run delivery-intel
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: npx delivery-intel@latest ${{ github.repository }} --v2 --json --output report.json

      - name: Check health score
        run: |
          SCORE=$(jq '.scores.delivery.score' report.json)
          echo "Health score: $SCORE / 100"
          if (( $(echo "$SCORE < 40" | bc -l) )); then
            echo "::error::Score $SCORE is below threshold (40)"
            exit 1
          fi

🏅 Badge

Once you have the dashboard deployed, you can show a live delivery score in any README:

[![Delivery Score](https://your-deployment-url/api/badge?repo=owner/repo)](https://github.com/ParthibanRajasekaran/delivery-intel)

The GET /api/badge?repo=owner/repo endpoint returns a Shields.io endpoint-badge payload. Score maps to color: < 20 red → < 40 orange → < 60 yellow → < 80 green → ≥ 80 bright green. Results cached 5 minutes.

Self-hosting: deploy the dashboard (npm run build && npm start or docker compose up dashboard) and replace your-deployment-url.

🏗️ Architecture

┌──────────────────────────────────────────────────────────────┐
│                      delivery-intel                          │
├──────────────┬───────────────┬───────────────────────────────┤
│   CLI        │   Dashboard   │   CI Workflow / Action        │
│  (npx)       │  (Next.js)    │   (action.yml)                │
├──────────────┴───────────────┴───────────────────────────────┤
│              Renderers (terminal, JSON, PR comment)           │
├──────────────────────────────────────────────────────────────┤
│          Verdict Engine  ·  Forensic Signal Engine            │
├──────────┬────────────┬──────────────┬───────────────────────┤
│ Scoring  │ Policies   │  Fix Packs   │  Recommendations      │
│ (conf-   │ (gates,    │  (copy-paste │  (ranked actions)     │
│  weighted)│  blocking) │   artifacts) │                       │
├──────────┴────────────┴──────────────┴───────────────────────┤
│  DORA Metrics (6) · Confidence · Evidence Sources · Caveats  │
├──────────────────────────────────────────────────────────────┤
│       Normaliser (raw API → typed EvidenceEvent stream)       │
├──────────┬────────────┬──────────────────────────────────────┤
│ GitHub   │ OSV.dev    │  Extractors (7 ecosystems)           │
│ REST API │ Vuln API   │  npm·pip·Go·Poetry·pnpm·Cargo·Gems  │
└──────────┴────────────┴──────────────────────────────────────┘

🛠 Tech Stack

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for dev setup, coding standards, and workflow.

git clone https://github.com/ParthibanRajasekaran/delivery-intel.git
cd delivery-intel
npm install
npm run validate   # lint + typecheck + test in one shot

📄 License

MIT. Use it however you want.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

delivery-intel

⚡ Quick Start

Why DORA metrics matter

All flags

Web Dashboard

Docker

📦 JSON Output Schema

🔐 Authentication

CI Integration

GitHub Actions Marketplace action

Evidence-backed PR guardrail (v2 engine)

npx (custom pipeline)

🏅 Badge

🏗️ Architecture

🛠 Tech Stack

🤝 Contributing

📄 License