catalyst-doc/.github/workflows/api-sync.yml at main · catalystctl/catalyst-doc · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
name: API sync check

# Two independent checks:
#
#  1. `api/openapi.json` is a valid OpenAPI 3.1 document and matches the served
#     copy (`public/openapi.json`). Hard gate: a stale served copy breaks the
#     Scalar reference at runtime.
#
#  2. Drift against the product repo's exported contract. The committed
#     artifact is regenerated deliberately with the docs agent
#     (`pnpm docs-agent api --source-repo <checkout>`) and lands through PR
#     review, so it can legitimately lag product `main` between releases. The
#     weekly job exports `catalyst-backend` from `catalystctl/catalyst` and
#     prints the operation delta. It is advisory (continue-on-error) so a
#     product-side change cannot turn the docs repo red on its own; promote it
#     to a hard gate only if the artifact must track every product commit.
on:
  push:
    branches: [main]
    paths: ['api/openapi.json', 'scripts/sync-openapi.mjs']
  pull_request:
    paths: ['api/openapi.json', 'scripts/sync-openapi.mjs']
  schedule:
    - cron: '0 6 * * 1'

jobs:
  api-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Validate OpenAPI artifact + served copy
        run: node scripts/sync-openapi.mjs --check

  drift-check:
    # Product HEAD is the reference only on the weekly run; on PRs the committed
    # artifact is reviewed directly.
    if: github.event_name == 'schedule'
    runs-on: ubuntu-latest
    continue-on-error: true
    steps:
      - uses: actions/checkout@v4
      - name: Check out Catalyst (product repo)
        uses: actions/checkout@v4
        with:
          repository: catalystctl/catalyst
          path: .catalyst-source
      - uses: pnpm/action-setup@v4
        with:
          version: latest
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Install the Catalyst backend toolchain
        run: pnpm install --frozen-lockfile
        working-directory: .catalyst-source
      - name: Export the product OpenAPI contract
        run: pnpm --filter catalyst-backend run openapi:export --out "$GITHUB_WORKSPACE/.openapi-exported.json"
        working-directory: .catalyst-source
      - name: Report drift against the committed artifact (advisory)
        run: |
          node -e '
          const { readFileSync } = require("node:fs");
          const ops = (file) => new Set(
            Object.entries(JSON.parse(readFileSync(file, "utf8")).paths)
              .flatMap(([p, item]) => Object.keys(item).map((method) => `${method.toUpperCase()} ${p}`)),
          );
          const committed = ops("api/openapi.json");
          const exported = ops(".openapi-exported.json");
          const added = [...exported].filter((op) => !committed.has(op));
          const removed = [...committed].filter((op) => !exported.has(op));
          console.log(`committed artifact: ${committed.size} operations; product export: ${exported.size}`);
          if (added.length) console.log(`missing from the docs artifact (+${added.length}):\n- ${added.join("\n- ")}`);
          if (removed.length) console.log(`in the docs artifact but gone from the product (-${removed.length}):\n- ${removed.join("\n- ")}`);
          if (!added.length && !removed.length) console.log("no drift: the committed artifact matches the product export");
          '