upstream-drift.yml

name: Upstream drift

# The client implementation must not silently drift with upstream: a change to
# the normative protocol documents has to be seen and assessed by a human. This
# runs daily and opens an issue when — and only when — a normative file changes.
on:
  schedule:
    - cron: '17 6 * * *'
  workflow_dispatch:

permissions:
  contents: read
  issues: write

jobs:
  drift:
    name: Check protocol baseline against upstream
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - name: Clone upstream
        run: git clone --quiet https://github.com/NodePassProject/Nowhere.git upstream-nowhere

      - name: Drift check
        id: drift
        run: |
          set +e
          OUT="$(bash conformance/scripts/drift-check.sh "$GITHUB_WORKSPACE/upstream-nowhere" 2>&1)"
          CODE=$?
          echo "$OUT"
          {
            echo 'report<<DRIFT_EOF'
            echo "$OUT"
            echo 'DRIFT_EOF'
          } >> "$GITHUB_OUTPUT"
          echo "code=$CODE" >> "$GITHUB_OUTPUT"
          exit 0

      - name: Summary
        run: |
          {
            echo '## Drift check'
            echo
            echo '```'
            echo '${{ steps.drift.outputs.report }}'
            echo '```'
          } >> "$GITHUB_STEP_SUMMARY"

      # The mirror image of the step below. An issue that is only ever opened
      # stays open after the baseline has been advanced, and a marker that is
      # permanently red is one nobody reads. The same check that raised it is
      # the thing entitled to withdraw it.
      - name: Close the drift issue once the baseline agrees again
        if: steps.drift.outputs.code == '0'
        uses: actions/github-script@v9
        with:
          script: |
            const report = ${{ toJSON(steps.drift.outputs.report) }};

            const existing = await github.rest.issues.listForRepo({
              owner: context.repo.owner,
              repo: context.repo.repo,
              state: 'open',
              labels: 'upstream-drift',
            });

            const body = [
              'The drift check passes again: `conformance/PROTOCOL_BASELINE` and',
              'upstream agree. Closing automatically.',
              '',
              '```',
              report,
              '```',
              '',
              `Run: ${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
            ].join('\n');

            for (const issue of existing.data) {
              await github.rest.issues.createComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: issue.number,
                body,
              });
              await github.rest.issues.update({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: issue.number,
                state: 'closed',
                state_reason: 'completed',
              });
            }

      - name: Open an issue on normative change
        if: steps.drift.outputs.code != '0'
        uses: actions/github-script@v9
        with:
          script: |
            const report = ${{ toJSON(steps.drift.outputs.report) }};
            const title = 'Upstream normative change detected';

            // One open issue at a time; append to it rather than filing duplicates.
            const existing = await github.rest.issues.listForRepo({
              owner: context.repo.owner,
              repo: context.repo.repo,
              state: 'open',
              labels: 'upstream-drift',
            });

            const body = [
              'A normative file changed upstream. The protocol baseline pinned in',
              '`conformance/PROTOCOL_BASELINE` no longer matches upstream, and the',
              'difference is in a file that defines behaviour rather than in',
              'implementation or surrounding docs.',
              '',
              '**Do not advance the baseline without reading the diff.** The tracking',
              'policy in `conformance/PROTOCOL_BASELINE` explains why the pin is held.',
              '',
              '```',
              report,
              '```',
              '',
              `Run: ${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
            ].join('\n');

            if (existing.data.length > 0) {
              await github.rest.issues.createComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: existing.data[0].number,
                body,
              });
            } else {
              await github.rest.issues.create({
                owner: context.repo.owner,
                repo: context.repo.repo,
                title,
                body,
                labels: ['upstream-drift'],
              });
            }