Include diff in spec-drift issue body (#39)

* Include diff in spec-drift issue body

Pretty-print both specs with --sort-keys so unrelated key reordering
doesn't trip the check, then attach a unified diff (truncated at 60 KB)
to the issue body inside a <details> block. Update the existing open
issue on subsequent runs so the diff stays current instead of pinning
to whatever week the drift first appeared.

* Simplify spec-drift body construction

- Capture the diff directly in the existing `if ! diff …` (errexit is
  already exempt inside `if`), removing the separate `-q` pre-check,
  the intermediate pretty-printed tempfiles, and the `|| true` workaround.
- Replace the multi-echo body wrapper with two `printf`s and a 1-line
  bash `&&` truncation marker.
- Pass `--label vendored --label upstream` to `diff` so the issue body
  shows meaningful headers instead of `/dev/fd/63`.

* Refresh openapi.json from upstream

Only `info.description` changed ("Last updated: April 23, 2026" →
"April 30, 2026"); the field is OpenAPI metadata that does not surface
in any generated Python, so re-running the regen pipeline produces no
changes under `ionq_core/`. The upstream-sorted diff matches the
preview posted on this PR.

Resolves #38.

* Collapse openapi.json diffs in GitHub PR views

`linguist-vendored=true` only excludes a file from repo language
statistics; it does not suppress diffs in PRs (see github-linguist's
`generated.rb` and github-linguist/linguist#3234). Add
`linguist-generated=true` so reviewers see openapi.json collapsed by
default — the spec is fetched from upstream by the regen pipeline and
isn't intended for line-by-line review (the actual semantic diff lives
in the spec-drift issue body now).

* Remove unnecessary comment

* Derive spec URL from openapi.json in spec-drift workflow

* Drop redundant spec-drift URL extraction test

Author: splch

.gitattributes

@@ -7,7 +7,7 @@ ionq_core/api/**      linguist-generated=true
 ionq_core/models/**   linguist-generated=true
 
 # Vendored upstream OpenAPI spec.
-openapi.json linguist-vendored=true
+openapi.json linguist-vendored=true linguist-generated=true
 
 # Lockfile.
 uv.lock linguist-generated=true

.github/workflows/spec-drift.yml

@@ -18,22 +18,34 @@ jobs:
         with:
           persist-credentials: false
       - name: Fetch latest spec
-        run: curl -sf https://api.ionq.co/v0.4/api-docs -o /tmp/latest-spec.json
+        run: |
+          BASE_URL=$(jq -r '.servers[0].url' openapi.json)
+          echo "BASE_URL=${BASE_URL}" >> "$GITHUB_ENV"
+          curl -sf "${BASE_URL}/api-docs" -o /tmp/latest-spec.json
       - name: Check for drift
         id: drift
         run: |
-          if ! diff -q <(python3 -m json.tool openapi.json) <(python3 -m json.tool /tmp/latest-spec.json) > /dev/null 2>&1; then
+          if ! diff -u --label vendored --label upstream <(python3 -m json.tool --sort-keys openapi.json) <(python3 -m json.tool --sort-keys /tmp/latest-spec.json) > /tmp/spec.diff; then
             echo "drifted=true" >> "$GITHUB_OUTPUT"
           fi
-      - name: Open issue
+      - name: Open or update issue
         if: steps.drift.outputs.drifted == 'true'
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          existing=$(gh issue list --label spec-drift --state open --json number --jq length)
-          if [[ "$existing" == "0" ]]; then
+          {
+            echo "The spec at ${BASE_URL}/api-docs has diverged from the vendored openapi.json. Fetch the new spec and regenerate the client."
+            printf '\n<details><summary>Diff (sorted, pretty-printed JSON)</summary>\n\n```diff\n'
+            head -c 60000 /tmp/spec.diff
+            [[ $(wc -c < /tmp/spec.diff) -gt 60000 ]] && printf '\n... (truncated)\n'
+            printf '```\n</details>\n'
+          } > /tmp/body.md
+          existing=$(gh issue list --label spec-drift --state open --json number --jq '.[0].number // empty')
+          if [[ -z "$existing" ]]; then
             gh issue create \
               --title "OpenAPI spec has changed upstream" \
-              --body "The spec at api.ionq.co/v0.4/api-docs has diverged from the vendored openapi.json. Fetch the new spec and regenerate the client." \
+              --body-file /tmp/body.md \
               --label spec-drift
+          else
+            gh issue edit "$existing" --body-file /tmp/body.md
           fi

openapi.json

@@ -127,18 +127,16 @@ def test_oas_patch_versions_match():
 
 
 def test_spec_path_matches_default_base_url():
-    # Without this, a DEFAULT_BASE_URL bump leaves spec-drift.yml curling the stale endpoint.
+    # Without this, a DEFAULT_BASE_URL bump leaves CONTRIBUTING.md pointing at a stale endpoint.
     spec_path = f"{urlparse(DEFAULT_BASE_URL).path}/api-docs"
     assert spec_path in CONTRIB
-    assert spec_path in SPEC_DRIFT_WF
 
 
 def test_spec_servers_path_in_docs():
     # Catches a stale openapi.json: code/docs bumped without regen, or fetched from the wrong version.
     spec = json.loads((ROOT / "openapi.json").read_text())
     spec_path = urlparse(spec["servers"][0]["url"]).path
     assert f"{spec_path}/api-docs" in CONTRIB
-    assert f"{spec_path}/api-docs" in SPEC_DRIFT_WF
 
 
 def test_single_spdx_year_across_package():