Mandate

Turn unwritten merge rules into enforceable GitHub checks.

A general PR obligation engine for changed files, labels, and checklist requirements. It runs locally by default, emits deterministic JSON and Markdown, writes a GitHub Step Summary when used as an action, and can update one stable PR comment when requested.

Install

pnpm add -D diffduty

Run locally:

pnpm diffduty scan --base origin/main --head HEAD --config .github/diffduty.yml --format markdown
pnpm diffduty scan --base origin/main --head HEAD --format json

GitHub Actions

Use actions/checkout with full history so git comparisons are available.

name: Mandate

on:
  pull_request:

jobs:
  diffduty:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v4
        with:
          version: 10.33.0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - uses: Eidetic-Research/mandate@v1
        with:
          mode: warn
          comment: true

Use mode: fail when findings should block the check. In warn mode, findings are reported but the action exits successfully unless a runtime error occurs.

Config

Create .github/diffduty.yml:

rules:
  - name: "database migration safety"
    severity: error
    when:
      files:
        - "db/migrations/**"
        - "prisma/migrations/**"
    require:
      any_of:
        - files:
            - "tests/migrations/**"
        - labels:
            - "migration-reviewed"
      checklist:
        - "Rollback path described"
  - name: "public API change"
    severity: warning
    when:
      files:
        - "openapi/**"
        - "schema.graphql"
        - "src/api/public/**"
    require:
      any_of:
        - files:
            - "CHANGELOG.md"
            - ".changeset/**"
        - labels:
            - "api-change-reviewed"

Example JSON

{
  "tool": "diffduty",
  "version": "0.1.3",
  "base": "origin/main",
  "head": "HEAD",
  "mode": "warn",
  "summary": {
    "findings": 1,
    "errors": 1,
    "warnings": 0
  },
  "findings": [
    {
      "id": "diffduty:example",
      "severity": "error",
      "title": "Example finding",
      "message": "Rule public API change matched, but none of its obligations were satisfied.",
      "evidence": {},
      "recommendation": "Satisfy one configured file, label, or checklist obligation."
    }
  ]
}

Example Markdown

DiffDuty found 1 finding.

1. Rule public API change matched, but none of its obligations were satisfied.
   Evidence: see JSON output for matched paths and labels.
   Recommendation: Satisfy one configured file, label, or checklist obligation.

Notes

• No telemetry.
• No LLM calls.
• No source-code upload.
• No external network calls except GitHub API calls for optional PR comments.
• The hidden PR comment marker is <!-- diffduty-report -->.

License

DiffDuty is licensed under the Business Source License 1.1. Evaluation, development, testing, security review, and use in public open-source repositories are allowed. Commercial use, including private/internal CI use, managed services, resale, hosted services, or competing products, requires a paid commercial license from Eidetic Research.

Each version converts to Apache-2.0 on the earlier of its configured Change Date or the fourth anniversary of that version's first public distribution. See LICENSE.

Development

pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm build:action

The action bundle is written to dist/index.js with @vercel/ncc. Marketplace publication notes are in MARKETPLACE.md.